docs: align architecture and user guides with the current code - #124
Merged
Merged
Conversation
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.
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.
What
Audit of
docs/anduser-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/)/loginnever existed.docs/architecture/{frontend,system-overview,backend}.mdanddocs/dev/templates-vs-web.mdlisted aLoginPage.svelteSPA 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 documentedNotFoundPage./scheduleswas missing from the system-overview route table and theApp.svelteroute tree; added alongside the/api/schedulesfamily and/api/chat/queue.backend.mdsaid "six tables"; there are eleven (schedules,schedule_runs,review_comments,chat_queue_items,chat_queue_statewere missing), plus the same omission in the system-overview DB row and directory layout.pwa.goonly serves manifest/service worker/icons/cat.webm;theme.css,index.css,menu.css,palette.cssare no longer standalone routes — they are inlined in the SPA shell (plusschedules.css/settings.css, which were missing from the lists).internal/chatqueue/,internal/server/chat_queue.go,chat_queue_drainer.go, andrequest.go; synced theServerandworkers.Managerstruct snapshots with the code.POST /api/chatreturns202 {"ok":true,"status":"queued"}, not"accepted"; Tailscale Serve only runs withPI_WEB_TOKENset; server startup also starts the schedule loop + queue drainer (skipped in dev mode);mention-autocompletehelpers actually live undercomponents/session/chat/; custom themes are picked in Settings → Appearance (the old header theme toggle is gone).session_info) and entry labels (label) append too.docs/README.md.User guides (
user-docs/en/)⌘//Ctrl+/(shortcuts modal) and⌘,/Ctrl+,(settings).llm-debug.md:pi-web statusis not a binary subcommand; the actual command is/pi-web status(and/pi-web path) from inside pi.install.md:?token=sets api_tokencookie and redirects to the token-stripped URL, so the token does not linger in the address bar or history.Translations
es fr de zh ja id ms vi th fil my km lo):install,keyboard-shortcuts,llm-debug,roadmapREADMEandpersonal-assistant, which still predated the skills /pi-web-ctladditions from feat(skills): add schedule, notes, and settings skills #117scripts/build_userdocs.pynow supports a--docsfilter so only changed guides are translated:build_userdocs.py --docs install roadmap— selected docs, all languagesbuild_userdocs.py es ja --docs install— both filters--docs) still translates every doc plushero.json.picalls 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 —whyandhero.jsonwere untouched and skipped by the filter.Verification
python3 scripts/build_site.pyassembles the VitePress source for all 14 locales from the edited English docs + regenerated translations./pi-web status,⌘/,?token=, shipped-roadmap entries).