[ymote]

Brings the app-author docs up to how OctoSense runs app agents on 2026-10-01: OctoSense main f52620c (pins App Hub 58c3c8ae, octos ae230ce0, Octoscript 5991dfae, Octoscript-Makepad 8f103d0c) and App Hub main 41bc959. Docs only.

Builds on #141 (guofoo, merged as 43da4310): this branch starts from that merge, keeps its AI services / host services / sockets content and extends it with what landed after it (OctoSense #190–#267). It does not touch the lines #121 (BH3GEI, open) changes: #121's hunks are README.md around line 139, README.zh-CN.md around line 129, QUICKSTART.md, FLOW.md and tools/octo; this PR changes README.md from line 240 on, README.zh-CN.md from line 221 on, and neither QUICKSTART.md, FLOW.md nor tools/octo.

What changed, and why

docs/AI-SERVICES.md and docs/AI-SERVICES.zh-CN.md (same content in both)

• The person talks to an app's agent directly (new subsection). There are three ways in, all in the person's lane. (1) The shell's "Ask " panel. The shell draws it for every app that has an agent (desktop: bar button, Shift+F8, Setup › Assistant). Its Stop stops only the person's turn; a separate row stops the system agent's task. (2) A card's sys.chat. (3) The app's own octos.* calls. The approvals surface's Stop stops both lanes. The phone has no touch entry to the panel yet. Code: crates/shell/src/app_chat/mod.rs, shell/menu.rs (setup.assistant.ask), approvals/mod.rs (stop_agent), mobile_app.rs.
• The system agent and app agents (new section). Covers which apps have an agent, the first-use sheet, prepared peers (card.<id>), what the system agent does (peer_list, peer_send_input, peer_gather, agents.list / agents.ask), two lanes, question routing (10-minute deadline), and purge on uninstall. Code: crates/shell/src/agents.rs, crates/ai-host/src/contained.rs, crates/shell/src/questions/mod.rs, crates/app-peers/src/broker.rs; #248.
• What an app's agent gets today (new table). It gets ask_user_question, the only kernel tool the gate allows (App Hub fix(nav): mirror drive-ETA centering into app.md embedded card #37, OctoSense tools: snap-to-png.py — headless widget-tree rendering for review/iteration (no display needed) #190). It gets files.list/read/search over its account folder (#205, Unix only). It also gets its tools.json tools, but these run only on a host service of the app's namespace, so only system apps' tools run. implemented_by: "app" answers an error. The generic host tools (net.fetch, storage.*, …) are admitted but implemented by no shell. Code: crates/shell/src/host_tools/{mod,script_apps,files,relay}.rs.
• storage block (accounts, agent_workspace, cache_max_bytes; App Hub fix(plan): drop a redundant borrow the 1.97 clippy gates on #44). Also covers the account folder layout the system apps adopted (#229), per-account agents (#233) and read_parent (#249).
• Status table rewritten for 1 Oct:
  • sys.digest: was "coming". Now the checker is merged (OctoScript ci: add clippy-gated CI; zero out own-crate warnings #40, OM Implement Attrs.elevation: the first shadow the renderer has drawn #50, in the shells' pin); the host side is still Unify on the org mains: Octoscript, Octoscript-Makepad and one makepad line #87 (open).
  • System toolbox: was "toolbox-peers off in the shipped shells". Now it is on in the phone's default build, granted only to os.* apps that declare research (none do yet), and has the tools toolbox.search/web_read/deep_crawl (crates/ai-host/src/toolbox_peers.rs, phone/Cargo.toml).
  • New rows: ask_user_question, host read tools, per-account agents and purge, the Mail and Calendar agents' card tools (#267), and model text plus sys.chat (#263, OctoScript Mono glyphs and single-hue bars in every mood, not just photo #53, OM The photo hero needed stroke weight, not scrim strength #68).
• Approvals. Adds outward and auto_approvable (App Hub fix(plan): drop a redundant borrow the 1.97 clippy gates on #44). Adds the router order and that rule conditions fail closed (#215), that every argument row must be seen before Approve (#218), and the audit to logs/tool-calls.jsonl (#222). Adds that an app's trigger: "person" does not count as the person's turn for approval rules (#215), and the relay budget of 32 calls a turn and 1000 a day.
• Glance: script (interactive Splash) cards, notify, tiles as background surfaces (#204), host services publishing for an agent (mail.notify, calendar.notify/agenda, #267), and OCTOSENSE_GLANCE_DEMO=mail (crates/shell/src/glance.rs).
• New section: AI-written text and in-card chat. Covers the model-copy and text-slot rules and the AI mark, the sys.chat / ChatEntry example from OctoScript's chat.card, and the host rules (publisher only, the host's transcript, user-only appends, limits, storage in accounts/<account>/chat/). It also says where chat is answered: the desktop card window and AppCard, not the Card runner or the phone's glance page. Code: crates/l0-chat/src/lib.rs, crates/shell/src/glance_chat.rs, OctoScript docs/ui-profile-l0.md §4.2 and §5.15.
• Version skew. The shells pin App Hub 58c3c8ae, and the manifest rules now come from octosense-app-contract 1.x (ADR 0005). Also: this repository's native-runtime.lock.json (OM cb66de07 → Octoscript dbd48cfb) predates sys.digest, sys.chat and model text in text slots.
• New errors: Add an account in the app before using its assistant, This app's manifest does not declare that assistant service. New peer methods: peer/tools/unregister, peer/purge. KNOWN_CAPABILITIES moved to crates/app-contract/src/manifest.rs.

docs/CAPABILITIES.md

• Adds rows for research and crawl. They need the research scope object, and the shells grant them only to os.* apps for now.
• prompt: points to ask_user_question. #204 is now merged.
• agent row: was "Nothing runs this agent yet …, which the shells' pinned App Hub refuses". Now it says what the shells actually give the agent.
• Adds rows for the storage.* fields and for reserved names (RESERVED_NAMES, App Hub fix(plan): drop a redundant borrow the 1.97 clippy gates on #44).

docs/HOST-SERVICES.md

• #204 is merged, so may_prompt is false for tiles and tool calls.
• Adds a calendar service row and a mail.notify row.
• Explains that a service method can also be an agent's tool.
• Mail secrets now live in secrets/os.mail/ (#223).
• Updates the KNOWN_CAPABILITIES path.

docs/GLOSSARY.md

• App peer: was "Today only native modules (Rinx) get one", which is wrong.
• Adds app agent (the person talks to it directly).
• Updates system agent and agent files.
• Adds model text and sys.chat.
• Adds research and crawl to the capability list. Updates the manifest schema path.

docs/SCRIPT-API.md: #204 is merged.

README.md, README.zh-CN.md (kept in sync)

• "AI in your app": was "A contained app cannot use it yet …". Now it is a dated table of what an app can do, and how that behaves in card-host.
• Capability list gains research and crawl. Removes "nothing yet". Adds storage fields and reserved ids.

AGENTS.md

• Agents are checked here only by hub check.
• The person talks to an agent in the shell's "Ask " panel.
• A store app's tools do not run yet.
• L0 cards with sys.chat, sys.digest or model text cannot be verified with this repository's runtime.
• The bundle-clean note matches.

Verified

• python3 tools/check-links.py: 0 broken, 0 pending. A local anchor check over every changed file (en and zh-CN headings) found no missing anchors.
• python3 -m unittest discover -s flows/tests -p 'test_*.py': 11 tests OK.
• I built hub from App Hub main 41bc959 (the app-contract, app-policy and app-hub crates) and ran hub stamp and hub check --allow-unsigned on a tools/octo new bundle. Every output marked ✓ run 2026-10-01 comes from this run:
  • ask_user_question agent: accepted.
  • web_search in agent.tools: refused.
  • mail.send in agent.tools: refused.
  • outward on a read tool: refused; on an act tool: warned.
  • dev.example.terminal: refused as reserved.
  • research without a scope: refused.
  • An unknown field at schema_minor 0: refused.
  • storage.accounts and agent_workspace: accepted.

Not verified

• Nothing was run in an OctoSense shell or on a device. The shell behaviour comes from reading code at f52620c, and the PRs it cites state what they ran.
• A store app with an agent reading data it writes under accounts/device/ is marked unverified.

Open questions for reviewers

• Should this repository's native-runtime.lock.json move to an Octoscript-Makepad that has OctoScript Mono glyphs and single-hue bars in every mood, not just photo #53 (for example 8f103d0c), so that card-host and card-studio here can check sys.chat, sys.digest and model-copy cards? That is a runtime change, not docs, so it is left out of this PR.
• The sys.digest host side (Unify on the org mains: Octoscript, Octoscript-Makepad and one makepad line #87) is still open, so the docs mark it "coming".

🤖 Generated with Claude Code