Skip to content

docs: align architecture and user guides with the current code - #124

Merged
setkyar merged 3 commits into
mainfrom
docs/align-with-code
Sep 19, 2026
Merged

setkyar merged 3 commits into
mainfrom
docs/align-with-code

Conversation

@setkyar

@setkyar setkyar commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

What

Audit of docs/ and user-docs/en/ against the current code, fixing claims that no longer match and content that was missing. Docs + translation tooling only — no app code changes.

Architecture (docs/)

  • /login never existed. docs/architecture/{frontend,system-overview,backend}.md and docs/dev/templates-vs-web.md listed a LoginPage.svelte SPA route. Auth is the Go-rendered token prompt (internal/ui/auth_page.go + embedded/auth.html), served by the auth middleware before the SPA loads. Replaced with the real behavior and documented NotFoundPage.
  • /schedules was missing from the system-overview route table and the App.svelte route tree; added alongside the /api/schedules family and /api/chat/queue.
  • SQLite schema drifted. backend.md said "six tables"; there are eleven (schedules, schedule_runs, review_comments, chat_queue_items, chat_queue_state were missing), plus the same omission in the system-overview DB row and directory layout.
  • CSS routes are gone. pwa.go only serves manifest/service worker/icons/cat.webm; theme.css, index.css, menu.css, palette.css are no longer standalone routes — they are inlined in the SPA shell (plus schedules.css/settings.css, which were missing from the lists).
  • Package layout: added internal/chatqueue/, internal/server/chat_queue.go, chat_queue_drainer.go, and request.go; synced the Server and workers.Manager struct snapshots with the code.
  • Numbers/behavior: running-status recent-activity window is 800 ms, not 3 s; POST /api/chat returns 202 {"ok":true,"status":"queued"}, not "accepted"; Tailscale Serve only runs with PI_WEB_TOKEN set; server startup also starts the schedule loop + queue drainer (skipped in dev mode); mention-autocomplete helpers actually live under components/session/chat/; custom themes are picked in Settings → Appearance (the old header theme toggle is gone).
  • Append-only claim: rename is not the only metadata append — auto-title (session_info) and entry labels (label) append too.
  • Added the design-system and metrics docs to docs/README.md.

User guides (user-docs/en/)

Translations

  • Regenerated all 13 non-English locales (es fr de zh ja id ms vi th fil my km lo):
  • scripts/build_userdocs.py now supports a --docs filter so only changed guides are translated:
    • build_userdocs.py --docs install roadmap — selected docs, all languages
    • build_userdocs.py es ja --docs install — both filters
    • A full run (no --docs) still translates every doc plus hero.json.
  • Cost control: 78 paid pi calls for a full resync (52 for this PR's guides + 26 for the feat(skills): add schedule, notes, and settings skills #117 drift) instead of 104 — why and hero.json were untouched and skipped by the filter.

Verification

  • python3 scripts/build_site.py assembles the VitePress source for all 14 locales from the edited English docs + regenerated translations.
  • Structural check on all 52 translated files: code-fence count, table rows, headings, and URLs all match the English source.
  • Relative-link check across all changed docs and translations: no broken links.
  • Spot-checked that every locale contains the new content (/pi-web status, ⌘/, ?token=, shipped-roadmap entries).

Architecture docs:
- Describe the Svelte SPA as the only live frontend; drop the nonexistent
  /login/LoginPage route (auth is the Go-rendered token prompt) and add
  /schedules everywhere routes are listed.
- backend.md: add internal/chatqueue + chat_queue*.go/request.go to the
  package layout, list all eleven SQLite tables, add /api/chat/queue, and
  sync the Server/Manager struct snapshots.
- CSS is inlined into the SPA shell; pwa.go no longer serves /theme.css,
  /index.css, /menu.css, /palette.css. Only /custom-themes.css is routed.
- Running-status recent-activity window is 800 ms, not 3 s.
- Tailscale Serve only runs when PI_WEB_TOKEN is set; server startup also
  launches the schedule loop and chat-queue drainer outside dev mode.
- chat returns 202 {"status":"queued"}; existing session files get three
  append paths (rename, auto-title, labels).
- Mention-autocomplete helpers live under components/session/chat/.
- Custom themes are picked in Settings -> Appearance (the header theme
  toggle is gone); index the design-system + metrics docs.

User docs:
- Roadmap: move shipped steering/queue, scheduler, display defaults, and
  git diff out of Next up/Planned.
- Keyboard shortcuts: document Cmd/Ctrl+/ (help) and Cmd/Ctrl+, (settings).
- llm-debug: /pi-web status is a pi command, not a binary subcommand.
- install: ?token= sets a cookie and is redirected away, so it does not
  linger in the address bar or history.
Regenerate es, fr, de, zh, ja, id, ms, vi, th, fil, my, km, and lo for
install, keyboard-shortcuts, llm-debug, and roadmap. This also picks up
English drift from #117 that the locale files had missed.

build_userdocs.py gains a --docs filter so only changed guides are
re-translated, instead of all seven docs plus hero for every language
(52 pi calls instead of 104). Hero translation still only runs for a
full rebuild.
The 13 locale README and personal-assistant files still predated the
skills / pi-web-ctl additions from #117. Regenerate both docs for every
locale so the whole translation set matches the English source.
@setkyar
setkyar merged commit cf48e13 into main Sep 19, 2026
6 checks passed
@setkyar
setkyar deleted the docs/align-with-code branch September 19, 2026 16:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant