Repository navigation
Live pointers to superseded docs/API_INTEGRATION.md need to be resolved #164
Description
Context
docs/API_INTEGRATION.md describes a July 2026 design where the API shelled out to csv_loader.sh. The current design (routers and services in api/, running FastAPI directly) replaced that long ago, and the file carries its own superseded note at the top.
The Project knowledge instructions already flag API_INTEGRATION.md as describing a superseded API. The problem is that the file is still referenced from live docs that new readers hit:
README.mdanddocs/QUICKSTART.mdboth link todocs/API_INTEGRATION.mdas "frontend ↔ backend endpoint mapping"docs/STARTER_GUIDE.md(PR docs: starter guide #63) adds a similar reference in its "Where to go next" pointer list
A new reader following any of these pointers lands on content that describes a design that has not shipped since July. The superseded banner at the top of API_INTEGRATION.md helps, but readers may not scroll back to the top after following a link into a specific section.
Options
Two ways to resolve, both honest. Product owner's call:
(a) Strengthen the superseded banner on docs/API_INTEGRATION.md itself. Add a prominent "DO NOT USE AS CURRENT REFERENCE" header, visible from any anchor link, with pointer to the current source of truth (api/routers/*.py). File stays in the repo for history; live references continue to work but readers are warned loudly.
(b) Remove references to docs/API_INTEGRATION.md from all live docs (README.md, docs/QUICKSTART.md, and docs/STARTER_GUIDE.md once PR #63 merges). File stays in the repo but new readers never find it through navigation. Current API documentation lives entirely in code comments + the OpenAPI schema at /api/docs.
(c) Both — strengthen the banner AND remove live pointers. Belt-and-braces.
Done when
- Decision taken (a/b/c) and recorded in a comment on this issue
- Edits applied in one PR, with the resulting state verified: a reader starting from the README cannot land on API_INTEGRATION.md without an explicit "this is historical" signal
Related
docs/API_INTEGRATION.md(the file itself, kept for history)README.md(contains a live pointer)docs/QUICKSTART.md(contains a live pointer)- PR docs: starter guide #63 adds another pointer in
docs/STARTER_GUIDE.md - D6 (closes Decide: Supabase data behind the Lovable frontend - migrate, retire or confirm none #69): ended Lovable platform dependency, which was the main reason API_INTEGRATION.md was superseded
- X4 (resolved 2 Nov): previously tracked the Supabase gap in this same file
Activity
docs: supersede API_INTEGRATION.md, fix starter/quickstart refs (#164 #…
amar-python commentedon Nov 8, 2026
Closing: the premise does not hold at
74c248fChecked
docs/API_INTEGRATION.mdonmaintoday. Two of the issue's load-bearing claims are no longer true:1. There is no superseded note on the file. The issue says "the file carries its own superseded note at the top". It does not —
grep -i -E "supersed|historical|out of date|do not use" docs/API_INTEGRATION.mdreturns nothing. So option (a) "strengthen the banner" would mean adding one, not strengthening.2. The file does not describe the July shell-out design. No mention of
csv_loader.shanywhere in it. Its architecture diagram iscsv-table-hub-main/ (React 19) → api/ (FastAPI) → PostgreSQL, and its endpoint table lists routes that exist at HEAD:GET /api/healthapi/main.py:111POST /api/csv/previewPOST /api/csv/uploadGET /api/csv/filesGET /api/csv/tables/{table}/rowsDELETE /api/csv/files/{id}POST /api/auth/login,POST /api/auth/oidc(prose, §Auth)It was last touched 4 Nov 2026 (
Merge pull request #197), i.e. after this issue was filed on 3 Nov. Whatever the July state was, the file has moved on.So the "Done when" — "a reader starting from the README cannot land on API_INTEGRATION.md without an explicit 'this is historical' signal" — is the wrong goal: the content is not historical, and labelling it so would make the docs less accurate, not more. Closing as not applicable rather than as done.
What was actually wrong, and what was fixed
Two real defects came out of the check, both fixed in #206:
docs/STARTER_GUIDE.mdpromised the file shows "every frontend↔backend API call". It documents 8 of the 22 live routes. Softened, with a pointer to the OpenAPI schema.docs/prompts/ART_FRAMEWORK.md:240told every agent reading the framework that "API_INTEGRATION.mddescribes a superseded API" — stale, and the likely origin of this issue's premise. Removed.The remaining genuine gap — 14 live routes the file never mentions — is tracked in #207 so it is scoped as "incomplete reference" rather than "superseded design".
The six live pointers (
README.md:146,docs/QUICKSTART.md:7,299,310,docs/STARTER_GUIDE.md:53,115) are left in place. They point at a partial but current doc, which is what they now say they do.Verified by Claude Code against
mainat74c248fGenerated by Claude Code
docs: replace API_INTEGRATION.md route table with pointer to /docs (#207