[ymote]

What

Two passes over docs/. The first is a fact audit (below). The second rewrites the guides to the README's standard: concepts first, plain English, no changelog noise, and every claim checked against the code. ADRs, plans and test reports are dated records, so they keep their history; they only get dated notes.

Rebased on #326 (composable Mail cards). The README and the guides now include #326's changes, each checked in the code:

• Mail's agent drafts and proposes replies, but has no tool that sends. The person sends by approving the exact message on the host's review with a physical touch, and developer mode cannot skip that.
• An opened card is a workspace, full screen on the phone and centred on the desktop. It has Card / Chat tabs, or Email / Chat for a Mail reply.
• Calendar ships on the phone.

Rewrite to the README standard

Guide (EN + zh)	Before	After	Grade
architecture.md	11,356 words	6,241	8.6 → 9.5
ai-services.md	4,890	2,890	9.1 → 9.6
architecture-walkthrough.md	4,321	3,169	9.0 → 9.6
mail-agent-events.md	1,093	1,062	8.8 → 9.5
local-ci.md (English only, by rule)	1,653	1,324	9.2 → 9.5

Four writer agents drafted the rewrites from a shared brief and a sheet of facts already verified. Independent graders then scored each against the README rubric: knowledge transfer, human voice, no needless detail, accuracy. They spot-checked 40 to 110 claims per guide against the code at the pins, and the guides were revised until they reached 9.5. Every finding was checked against the code before it was applied. Two were rejected with evidence: "only enabled is required" (the tool's input_schema requires more) and deleting the unverified marker (AGENTS.md rule 9 requires it).

• architecture.md:
  • the full reference, with no PR numbers or dates;
  • a native-apps table with the hosting for each platform and the shell defaults;
  • the system agent's host tools and their conditions;
  • §5 as the one canonical approval order, which the README and the walkthrough now link to;
  • a source map that includes code outside this repository, at the pins;
  • a checked list of where the code and the ADRs disagree.
• ai-services.md: the moving parts, the trust model, an honest status table by kind of app, the octos.* calls, answers and errors, the model service, the toolbox, and how to run and test locally.
• Walkthrough: one Calendar question traced through the code, step by step, naming the file and symbol to open at each step.
• mail-agent-events.md and local-ci.md: tightened, with their limits and a reading list.
• Images:
  • ai-services-processes.png loses an "inbox" queue the kernel doesn't have (the broker queues);
  • ai-services-cross-app-call.png loses "(Rinx send)", since Rinx registers no confirm: app sheet.
• README corrections:
  • No shipped app opens the person's lane from its own UI; Rinx uses only open_context, for its mini apps.
  • A native agent gets its folder whatever agent_workspace says.
  • Keys aren't owner-only on Windows.

Code issues found along the way (not fixed here; for maintainers)

Corrected after a re-check on main (d9d3b8be). The first version of this list was wrong on three counts:

• the first-use sheet does not say "No files";
• the in-process Terminal cannot run commands, and release packages are not exposed;
• Task's hosting is not a bug.

1. Mail's Inbox stops syncing for anyone who leaves new-mail processing off, which is the default.
   • Every Inbox sync queues an event per new message (incoming::collect), and that includes the Mail window's own sync. The queue is saved in the mailbox file.
   • Only the event worker removes events (agent_events.rs:709), and it runs only while processing is on.
   • Once 128 events are queued, every Inbox sync that finds new mail fails with "Incoming mail queue is full" (incoming.rs:152-154). It fails before saving anything, so new Inbox mail stops appearing.
   • Turning processing on later drains the backlog one event per poll (60 s by default). It runs an agent turn for each old message.
2. On Windows, the AI pane can type commands into an unsandboxed Terminal.
   • Windows process apps run without a sandbox (sandbox/mod.rs). The process Terminal offers its own run on the AI bus.
   • The system agent's terminal.run requires sandbox::launch_sandboxed (system_chat/grants.rs:205), but the bus never checks it for the pane.
   • The person still approves each command, with its exact text, on the host's sheet, and no standing rule can approve it.
   • Release packages have no AI pane, so they are not affected.
   • Related dead code: module_host::host_executor swaps in a Terminal executor that would answer run. Nothing can reach it:
     • the bus advertises the module's own read-only manifest, which is read before the swap (module_host.rs:573);
     • the pane refuses any tool a manifest doesn't declare.
3. Six native agents get a folder they declare they don't need.
   • Calculator, Clock, Notes, Reminders, Weather and the Terminal declare agent_workspace: "none".
   • host_tools::agent_workspace_in (host_tools/mod.rs:549-550) still gives each of them a private folder and the files.* tools.
   • The first-use sheet agrees with what they get ("<App>'s files on this device"), because it never sees the declaration (apps.rs:280).
   • This is a least-privilege issue only: each agent reaches its own folder, not the person's files.

Erratum in this PR's docs. In "Where the code and the ADRs disagree" (docs/architecture.md, item 8, EN and zh), the line saying terminal.run "is never offered" on Windows is true of the system agent only. See issue 2.

Fact audit (first pass)

This brings everything under docs/ up to date with the code, following the README rewrite in #331. Several recent merges left the docs stale:

PR	What changed
#309, #329	Calculator, Clock, Notes, Reminders and Weather became native apps with agents, on desktop and phone.
#330	The Terminal got its own agent.
#321	Mail started handling incoming events.
#257	Desktop release packages ship no process-app binary.

Five independent reviewers audited every file in docs/ against the code at 89e6c42f: the guides, the ADRs, the plans and the test reports. Before applying a finding, I confirmed it in the code, git log or gh. A final independent review of this diff caught 11 more problems, including two over-claims of mine, and all of them are fixed:

• My summary of the Mail test said more than the record shows.
• I first wrote Task as "off by default", but shells: off only means no shell links it as a module.

Factual fixes

• Native agents.
  • ai-services.md, architecture.md and the walkthrough no longer say that Rinx is the only native app with an agent, that the Terminal has none, or that nothing uses the peer link.
  • They now describe:
    • the five Makepad apps' agents (OctosPeer + serve_tools, agent_workspace: "none");
    • their system_tools;
    • the Terminal's own_tools;
    • that a native app's peer lives with its open window.
• terminal.run is registered only while the Terminal runs as its own sandboxed process (system_chat/grants.rs). ai-services.md said it worked "in both module and process hosting". The README said nothing about the condition.
• Release packages ship only octosense and the kernel, so a packaged desktop runs the Terminal in-process and read-only. This is now said in the README, architecture.md and ADR 0004.
• Task (Task Manager) is a process-only native app with no agent, started from the desktop catalog. It is named as a process app in the README, architecture.md (native-apps table) and the walkthrough.
• AGENT.md and skills.
  • The admitted text reaches every turn of an allowed script app (agent_events::install_guidance).
  • Mail declares eight tools, not just mail.notify.
  • agents.provision and agents.status exist and accept only os.mail.
• Smaller corrections.
  • Windows also keeps keys in the profile.
  • The window-manager override is at ~/.octosense/wm/apps.splash.
  • The phone's glance page runs L0 cards.
  • Catalog-only upstream Makepad apps run unsandboxed.
  • PeerRequest and PeerReply don't exist; the docs now refer to octos_peer frames.
  • The Ask panel sends TurnFrom (Person).
  • The default build already has octos-core.
  • The packaged octos-kernel is part of the kernel-launch order.
  • The octos child process has its own Tokio runtime, one worker per core, and is now in the walkthrough's thread table.
• local-ci.md. ci-local-merge.sh doesn't cover release-desktop.yml. A second run in the same clone exits with 75. The Linux-host steps are checked when present but not required. rom.yml's real paths are now listed.
• ADRs. These get dated notes that leave the history as it was:
  • ADR 0002 is "Proposed; partly implemented".
  • ADR 0004 has three plan items still open, and its Status says so. It also gets notes on Task, the Terminal's agent, the system agent's extra host tools, Linux sandbox: the next build's inputs stay read-only under home:rw #238 closing the Landlock gap, and what tools ship.
  • ADR 0005 notes the app-contract 1.1.0 state.
  • Home ADR 0001 notes that the ROM now ships Home, the Bridge and Quickstep.
  • Home ADR 0002 says where the calendar-01 card actually lives.
  • The ADR index's statuses are updated, and it now explains the home ADRs' path mapping.
• Plans. The Photos memories and platform-icons plans are marked done, with their PRs.
• Diagrams. In ai-services-processes.png the peer link is no longer drawn dashed and "(planned)". In ai-services-cross-app-call.png, peer/input is no longer "(in progress)", and the Calendar → mail.send hop is now dashed and labelled "(planned)", since no app has a mail.send tool yet. The Mermaid and ASCII diagrams in architecture.md and ai-services.md now show the native apps that use the peer link.

Parity and rendering

• mail-agent-events.zh-CN.md gets the sequence diagram it was missing. Its paragraphs now match the English.
• The Chinese ai-services, architecture, the walkthrough and the mail-events test report regain rows, details and labels that had been shortened or changed.
• <app>, <App> and <id> outside code are escaped in 25 lines. GitHub stripped them as HTML tags, so "Ask " displayed as "Ask ".
• History told in the present tense (review dates, "glance: resolve sys.digest sources from host-held digests (ADR 0002 M4) #87 is historical tracking") and a UI-minutiae aside are removed.

Verification

• The rewritten guides were graded by independent agents, which spot-checked 40 to 110 claims each against the code at HEAD and at the octos, App Hub, Makepad and Rinx pins. The first grades were 8.6 to 9.2, and every guide was revised to 9.5 or higher (see the table above).

• A link check of every Markdown file in the repository finds the same 301 pre-existing problems on main and on this branch, all in files this PR doesn't touch. The branch adds no broken link or anchor. Every anchor other files and repositories link to is kept.

• The link checker uses GitHub's slug rules. It found no broken relative link or anchor in the README, the desktop README or any file under docs/.

• No raw tags remain outside code.

• python3 -m unittest discover -s rom/tests -p test_no_local_paths.py: OK.

• git diff --check: clean.

• The test reports' links and hashes were rechecked. Every recomputable hash matches, and the evidence contains no secrets or personal paths.

• An independent reviewer checked this diff before commit (accuracy, Chinese parity, table, Mermaid and ASCII rendering). It found 11 problems; after the fixes its verdict was "ready to commit".

• No code changed. Two commands in the walkthrough changed:

  • The comment above the kernel run command now says the default build already has the kernel service.
  • The redundant --features octos-core was dropped from it.

  Neither command was run.

🤖 Generated with Claude Code