docs: reconcile 03/05/README/08/09 with shipped code#266
Merged
Conversation
Mark shipped features that still read as backlog (consolidation, merge_entities, place/event kinds, proposed-entities queue, doc/photo connectors), fix the stale /ui path and 2.0 branch refs, document the proposed-entity review endpoints, and correct the vCard-photo row. Refs #122, #222. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YKt6y3Rk498eBqneiMKHpM
There was a problem hiding this comment.
Pull request overview
Docs-only update to bring the project’s design/roadmap/README/UI docs in line with shipped server behavior and current branch/UI routing conventions, reducing drift between documented interfaces and the actual codebase.
Changes:
- Update README CI/branch-protection references and expand documented REST surfaces (proposed-entities queue, entity photo listing, place/event entity kinds, clustering scripts).
- Mark shipped milestones/features as shipped in the roadmap/design docs (ingest foundations, reference connectors, consolidation, merge_entities).
- Correct contacts-prep documentation to reflect vCard
PHOTOpreservation intoCONTACTS_RAW_DIR.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates CI badge/branch refs and expands documented REST/status surfaces to match shipped features. |
| docs/03-ob2-design.md | Adds shipped-vs-backlog and schema-drift notes; updates consolidation and UI path documentation. |
| docs/05-roadmap.md | Marks multiple milestones/backlog items as shipped and updates UI/token path notes. |
| docs/08-preparing-contacts.md | Updates vCard PHOTO handling to reflect shipped preservation behavior. |
| docs/09-contacts-ui.md | Documents proposed-entity review queue endpoints and entity photo listing endpoint for the UI surface. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | `GET /api/v1/entities/:id/photo` | — | image bytes (`404` if none) | | ||
| | `GET /api/v1/entities/photos` | — | contact reference-photo list for the photo-exif face matcher (#112) | | ||
|
|
||
| **Proposed-entity review queue** (#119/#143 — nothing becomes an entity without approval; same `/api/v1/entities` family): |
|
|
||
| - **REST** — `POST /api/remember`, `POST /api/recall`, `POST /api/search`, `POST /api/timeline`, `POST /api/about_entity`, `GET /api/artifact/:id` | ||
| - **Entity curation** (`/api/v1/entities`, core-owned — never via a connector, see [`docs/03-ob2-design.md §7`](docs/03-ob2-design.md)) — `GET /api/v1/entities/duplicates` (rank likely-duplicate person entities by shared phone/email + name similarity; read-only), `POST /api/v1/entities/merge` (`{keep_id, absorb_id}` — tombstones the absorbed entity, never deletes it, and re-points its aliases/links/relations to the survivor), plus the contacts-UI CRUD surface — list/get, create, `PATCH` fields, add/remove aliases & relationships, and photo upload/download (all under `/api/v1/entities`, see [`docs/09-contacts-ui.md`](docs/09-contacts-ui.md)). A browser UI over these lives at `/<token>/ui/contacts.html` (token-only, #169 — see the curation note above). | ||
| - **Entity curation** (`/api/v1/entities`, core-owned — never via a connector, see [`docs/03-ob2-design.md §7`](docs/03-ob2-design.md)) — `GET /api/v1/entities/duplicates` (rank likely-duplicate person entities by shared phone/email + name similarity; read-only), `POST /api/v1/entities/merge` (`{keep_id, absorb_id}` — tombstones the absorbed entity, never deletes it, and re-points its aliases/links/relations to the survivor), plus the contacts-UI CRUD surface — list/get, create, `PATCH` fields, add/remove aliases & relationships, and photo upload/download (all under `/api/v1/entities`, see [`docs/09-contacts-ui.md`](docs/09-contacts-ui.md)). The **proposed-entity review queue** (nothing becomes an entity without approval): `GET /api/v1/entities/proposed`, `POST /api/v1/entities/proposed/:id/approve`, `POST …/proposed/:id/reject`, `POST …/proposed/stage-from-directory` (#119/#154), plus `GET /api/v1/entities/photos` (the face-match photo source, #112). A browser UI over these lives at `/<token>/ui/contacts.html` (token-only, #169 — see the curation note above). |
…lot)
GET /entities/proposed returns { proposals } with ?status&limit (no
offset); soften 'nothing becomes an entity without approval' to name
the trusted POST /api/v1/entities direct-create path. Refs #222.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YKt6y3Rk498eBqneiMKHpM
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #122
Closes #222
Summary
Reconcile the design/roadmap/README/setup docs with shipped code. Several features still read as backlog/future though they've shipped, and a few paths/branch refs were stale. Docs-only — no code change.
Docs changed
src/consolidate.js); schema-drift note (merged_into,alias_tombstones,unresolved_aliases,proposed_entities,contact_directory) pointing at.claude/rules/data-model.md;/ui/contacts.html→/<token>/ui/contacts.html(feat(server): make the web UI token-only (no open /ui, remove API-key bar) #169).merge_entitiesmoved out of Backlog (shipped feat: entity merge + duplicate detection (core curation admin API) #75);/ui→ token path (feat(server): make the web UI token-only (no open /ui, remove API-key bar) #169); "no CSV import yet (feat(contacts): CSV contact import #126)" note.GET /api/v1/entities/photos; place/event kinds +places:cluster/events:clusterin Status; CI badge + branch-protection refs2.0→main.GET /entities/photosrow + the pending feat(contacts): Name lookup → Candidates → Contacts — directory management + clearer pipeline #219 Candidates/Promote display-rename note.PHOTOrow: preserved toCONTACTS_RAW_DIR(feat: preserve vCard PHOTO on contact import #74), not "dropped on import".Reviewer notes
src/server.js:784/822/835/844/855,package.json:15/23/24./pre-doc-review: APPROVE, 0 findings.gphotos-takeoutfold-in). The "no hint-approval workflow" note from docs: reconcile 03-ob2-design & 05-roadmap with shipped code #122 was deliberately not added — theproposed_entitiesapproval queue shipped, so it would be wrong.