ReviewOS

stacks/uplink

docs: the README calls index.stx the dashboard, and docs/ does not exist

#35
Open glennmichael123 opened this 9 days ago ·
9 days ago

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#L117 maps resources/views/index.stx to the dashboard. That file documents itself as the public page for uplink.stacksjs.com at resources/views/index.stx#L3, and the dashboard is resources/views/dashboard.stx, which says so at resources/views/dashboard.stx#L3. A contributor following the Layout section edits the marketing homepage when they meant the dashboard, and the reverse.
  • README.md#L121 tells contributors to run the tests through ./pantry/.bin/bun. /pantry is gitignored at .gitignore#L18 and is absent from a fresh clone, so the one documented test command fails on first use.
  • README.md#L105 lists ./buddy dev as "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#L18 points BunPress at ./docs, config/docs.ts#L21 is nav: [], and the sidebar at config/docs.ts#L35 holds one entry, an Introduction link at config/docs.ts#L40. No docs/ directory exists. config/docs.ts#L9 states that buddy deploy builds that site, and .github/workflows/deploy.yml#L185 runs ./buddy deploy --prod --yes on 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 at app/Uplink/settings.ts#L17, the directory at app/Uplink/settings.ts#L14 holding settings and the run history in the SQLite file at app/Uplink/settings.ts#L16, or the com.stacksjs.uplink Keychain item named at app/Uplink/settings.ts#L19.
  • README.md#L107 sends the reader to the UPLINK_* 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 the Settings shape at app/Uplink/settings.ts#L22 instead.
  • README.md#L101 documents ./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

  1. Correct the three lines in README.md. Line 117 names resources/views/dashboard.stx as the dashboard and resources/views/index.stx as the public page. Line 121 becomes bun test tests/unit/uplink. Line 105 names the path the dev server serves the dashboard at.
  2. Create docs/ with index.md and pages for install, the permissions and why each is required, a configuration reference, the security model, troubleshooting, and uninstall.
  3. Write the configuration reference from both sources of truth: the UPLINK_* block in .env.example for the from-source service, and the Settings interface in app/Uplink/settings.ts for the downloaded app, saying plainly which values apply to which.
  4. 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 at app/Uplink/settings.ts#L14, and the log at app/Uplink/settings.ts#L17.
  5. Fill in nav at config/docs.ts#L21 and the sidebar at config/docs.ts#L35 so every page from step 2 is reachable.
  6. Keep README.md as 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.json and the token in the Keychain; the from-source service reads .env and uses a separate bundle id. A page that blurs them misinstructs half its readers.
  • No new routes. BunPress already serves docs/ per config/docs.ts#L9, so nothing is added to routes/.
  • No em-dashes or en-dashes in any page, per the house rule in AGENTS.md.

Acceptance

  • No line in README.md contradicts the file it names. resources/views/index.stx is described as the public page and resources/views/dashboard.stx as the dashboard.
  • The test command in README.md runs on a fresh clone after bun install, with no ./pantry/.bin/bun path in it.
  • buddy dev serves the docs site, and every entry in the config/docs.ts nav 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.

Sign in to comment on this issue.