Part of #6.
The README is the only documentation Uplink has, and it carries two audiences at once: a contributor cloning the repository and someone who downloaded the signed app from the release page. Three of its lines send the reader somewhere that does not exist or does not match, and almost everything the second audience needs after the app is running is absent. The BunPress seam that would hold that material is configured and empty.
What is there today
README.md#L117mapsresources/views/index.stxto the dashboard. That file documents itself as the public page for uplink.stacksjs.com atresources/views/index.stx#L3, and the dashboard isresources/views/dashboard.stx, which says so atresources/views/dashboard.stx#L3. A contributor following the Layout section edits the marketing homepage when they meant the dashboard, and the reverse.README.md#L121tells contributors to run the tests through./pantry/.bin/bun./pantryis gitignored at.gitignore#L18and is absent from a fresh clone, so the one documented test command fails on first use.README.md#L105lists./buddy devas "The dashboard: setup status, what it is doing, recent texts" and names no URL, so the reader has to guess the path or read the dev server output to find it.config/docs.ts#L18points BunPress at./docs,config/docs.ts#L21isnav: [], and the sidebar atconfig/docs.ts#L35holds one entry, an Introduction link atconfig/docs.ts#L40. Nodocs/directory exists.config/docs.ts#L9states thatbuddy deploybuilds that site, and.github/workflows/deploy.yml#L185runs./buddy deploy --prod --yeson every push that clears CI, so each deploy builds a docs site with nothing in it.- Nothing documents what a downloaded-app user needs once past the install steps at
README.md#L41: the log atapp/Uplink/settings.ts#L17, the directory atapp/Uplink/settings.ts#L14holding settings and the run history in the SQLite file atapp/Uplink/settings.ts#L16, or thecom.stacksjs.uplinkKeychain item named atapp/Uplink/settings.ts#L19. README.md#L107sends the reader to theUPLINK_*block that starts at.env.example#L141. That block is the only reference for those values anywhere, and it configures the from-source service, not the downloaded app, which reads theSettingsshape atapp/Uplink/settings.ts#L22instead.README.md#L101documents./buddy uplink:uninstall, which stops and unregisters the from-source service. There is no removal path documented for the downloaded app, and nothing tells a user what to do when a text goes unanswered.
Proposal
- Correct the three lines in
README.md. Line 117 namesresources/views/dashboard.stxas the dashboard andresources/views/index.stxas the public page. Line 121 becomesbun test tests/unit/uplink. Line 105 names the path the dev server serves the dashboard at. - Create
docs/withindex.mdand pages for install, the permissions and why each is required, a configuration reference, the security model, troubleshooting, and uninstall. - Write the configuration reference from both sources of truth: the
UPLINK_*block in.env.examplefor the from-source service, and theSettingsinterface inapp/Uplink/settings.tsfor the downloaded app, saying plainly which values apply to which. - Write the uninstall page as an exact sequence per install path, naming the LaunchAgent, the Keychain item at
app/Uplink/settings.ts#L19, the data directory atapp/Uplink/settings.ts#L14, and the log atapp/Uplink/settings.ts#L17. - Fill in
navatconfig/docs.ts#L21and the sidebar atconfig/docs.ts#L35so every page from step 2 is reachable. - Keep
README.mdas the short landing page and link it to the docs site rather than growing it.
Requirements
- Every path the README names has to match that file. The Layout section is what a new contributor trusts first, so each claim is checked against the file's own header comment rather than remembered.
- The docs pages state the real paths, read from
app/Uplink/settings.ts. The log, data directory, database and Keychain item are defined there, so the docs quote those values instead of restating them from memory. - The two install paths stay distinct on every page. The downloaded app keeps preferences in
settings.jsonand the token in the Keychain; the from-source service reads.envand uses a separate bundle id. A page that blurs them misinstructs half its readers. - No new routes. BunPress already serves
docs/perconfig/docs.ts#L9, so nothing is added toroutes/. - No em-dashes or en-dashes in any page, per the house rule in
AGENTS.md.
Acceptance
- No line in
README.mdcontradicts the file it names.resources/views/index.stxis described as the public page andresources/views/dashboard.stxas the dashboard. - The test command in
README.mdruns on a fresh clone afterbun install, with no./pantry/.bin/bunpath in it. buddy devserves the docs site, and every entry in theconfig/docs.tsnav and sidebar resolves to a page rather than a 404.- A reader who only downloaded the app can find, from the docs alone, where the log is, where their data is, what the Keychain item is called, and how to remove all of it.
- The troubleshooting page answers the unanswered-text case with a first step that names the log path and
./buddy uplink:doctor.