docs: connect app hosting to agents and rendering

AGENTS.md

@@ -0,0 +1,25 @@
+# Working on the OctoScript website
+
+Read [README.md](README.md) and the bilingual app guides under
+`src/content/guides/octosense-apps.*.md` before changing architecture copy.
+
+- This repository owns website content and a pinned demonstration package.
+  It does not build the production OctoSense shell or run its app agents.
+- Keep English and Chinese claims aligned. Add a guide to `src/data/docs.ts`,
+  both locale lists in `src/data/content.ts`, and `scripts/doc-links.mjs`.
+- Distinguish workflow source, contained Splash apps, L0 card realization,
+  renderer nodes and native mounting. Explain new terms at their first use.
+- Trace permissions and tools to their host implementation. A language
+  capability, bundle declaration or UI demo does not establish a runtime
+  service, account access or cross-app grant. State current integration gaps.
+- Preserve source provenance: corrections to checked-in upstream snapshots
+  require updated hashes and an explicit correction record in `sources.json`.
+  The consuming app's runtime and Cargo locks select its actual implementation.
+- Keep browser sample state and historical design examples labelled. Preserve
+  demo behavior and the prebuilt WASM package unless the task changes them.
+- For content/navigation changes run `npm run test:unit`, `npm run build`,
+  relevant existing Playwright checks, and `git diff --check`. Include a new
+  guide in the existing guide-navigation test loop when adding a route.
+  Native build/device commands documented here need separate validation.
+- Changes to `main` trigger the Pages deployment workflow. Prepare a PR for
+  review; do not merge or deploy as part of a documentation task unless asked.

README.md

@@ -4,9 +4,11 @@ English | [简体中文](README.zh-CN.md)
 
 > **Building an OctoSense app?** You do not need this repository: it is the source of the language website <https://octoscript.org/>, useful background reading but not part of building, checking or publishing an app. Start from the [OctoSense organization profile](https://github.com/OctoSense-org)'s reading order: [OctoScript-App-Design-Flow `AGENTS.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/AGENTS.md) → [`flows/README.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/README.md) → [`docs/QUICKSTART.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/QUICKSTART.md).
 
-The independent bilingual website for [Octoscript](https://github.com/OctoSense-org/Octoscript), maintained in [OctoSense-org/Octoscript-website](https://github.com/OctoSense-org/Octoscript-website). English is at `/`; Simplified Chinese is at `/cn/`.
+The independent bilingual website for [Octoscript](https://github.com/OctoSense-org/Octoscript), maintained in [OctoSense-org/OctoScript-website](https://github.com/OctoSense-org/OctoScript-website). English is at `/`; Simplified Chinese is at `/cn/`.
 
-The site covers the DSL's motivation, syntax, host authority, L0–L3 rendering layers, UI capability levels, Splash, native composition and agent tooling. Eight guides in each language explain the contracts on the page. A searchable component catalog and a real Makepad/WebAssembly lab accompany the design-to-component examples. Light and dark themes are supported.
+The site covers the DSL's motivation, syntax, host authority, L0–L3 rendering layers, UI capability levels, Splash, native composition and agent tooling. Nine guides in each language explain the contracts on the page. A searchable component catalog and a real Makepad/WebAssembly lab accompany the design-to-component examples. Light and dark themes are supported.
+
+The [app and agent guide](src/content/guides/octosense-apps.en.md) follows native Rust, Splash and L0 apps into OctoSense, including human/system conversations, app data, tool grants and Tokio tasks. Contributor instructions are in [AGENTS.md](AGENTS.md).
 
 ## Run locally
 
@@ -41,7 +43,7 @@ The build checks Astro/TypeScript and writes the static site to `dist/`. Playwri
 - `src/styles/`: typography, responsive layout and light/dark theme tokens.
 - `public/examples/provenance.json`: image source hashes and the archived design review's status.
 
-All imports resolve within this repository. Edit website content here. To refresh an upstream snapshot, review the corresponding language-repository document, copy it into the same snapshot path, and update its manifest hash and provenance. Changes in the language repository do not silently change the website.
+All imports resolve within this repository. Edit website content here. To refresh an upstream snapshot, review the corresponding language-repository document, copy it into the same snapshot path, and update its manifest hash and provenance. Website-local architecture corrections are recorded separately in `sources.json`, retaining the original snapshot base and date. Changes in the language repository do not silently change the website.
 
 The design inspector shows recorded mappings and native captures; it does not run a vision model. The archived review still records remaining visual differences. Purchased Sketch assets are not redistributed. The school, delivery and travel cards use browser-only sample data; their approvals do not run workflows or external actions.
 

README.zh-CN.md

@@ -4,9 +4,11 @@
 
 > **要开发 OctoSense 应用？** 你不需要这个仓库：它是语言网站 <https://octoscript.org/> 的源码，可作为背景阅读，但不属于开发、检查或发布应用的步骤。请按 [OctoSense 组织主页](https://github.com/OctoSense-org)给出的顺序阅读：[OctoScript-App-Design-Flow `AGENTS.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/AGENTS.md) → [`flows/README.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/flows/README.md) → [`docs/QUICKSTART.md`](https://github.com/OctoSense-org/OctoScript-App-Design-Flow/blob/main/docs/QUICKSTART.md)。
 
-[Octoscript](https://github.com/OctoSense-org/Octoscript) 的独立双语网站，维护于 [OctoSense-org/Octoscript-website](https://github.com/OctoSense-org/Octoscript-website)。英文版位于 `/`，简体中文版位于 `/cn/`。
+[Octoscript](https://github.com/OctoSense-org/Octoscript) 的独立双语网站，维护于 [OctoSense-org/OctoScript-website](https://github.com/OctoSense-org/OctoScript-website)。英文版位于 `/`，简体中文版位于 `/cn/`。
 
-网站介绍这门 DSL 的设计动机、语法、宿主权限、L0–L3 渲染分层、UI 能力等级、Splash、原生组合以及 Agent 工具链。每种语言各有八篇指南，逐一讲解页面上的各项约定。设计到组件的示例配有可搜索的组件目录和一个真实的 Makepad/WebAssembly 实验室。支持浅色和深色主题。
+网站介绍这门 DSL 的设计动机、语法、宿主权限、L0–L3 渲染分层、UI 能力等级、Splash、原生组合以及 Agent 工具链。每种语言各有九篇指南，逐一讲解页面上的各项约定。设计到组件的示例配有可搜索的组件目录和一个真实的 Makepad/WebAssembly 实验室。支持浅色和深色主题。
+
+[应用与 Agent 指南](src/content/guides/octosense-apps.cn.md)追踪原生 Rust、Splash 和 L0 应用如何进入 OctoSense，并说明用户／系统对话、应用数据、工具授权与 Tokio 任务。协作规则见 [AGENTS.md](AGENTS.md)。
 
 ## 本地运行
 
@@ -41,7 +43,7 @@ npm run test:e2e
 - `src/styles/`：字体排印、响应式布局以及浅色/深色主题 token。
 - `public/examples/provenance.json`：图片来源哈希以及已归档设计评审的状态。
 
-所有导入都在本仓库内解析。网站内容请在这里编辑。若要刷新某个上游快照，请先审阅语言仓库中对应的文档，把它复制到相同的快照路径，并更新清单中的哈希和来源记录。语言仓库的变更不会在不知不觉中改变网站。
+所有导入都在本仓库内解析。网站内容请在这里编辑。若要刷新某个上游快照，请先审阅语言仓库中对应的文档，把它复制到相同的快照路径，并更新清单中的哈希和来源记录。网站本地的架构修正单独记录在 `sources.json`，保留最初快照的基准提交与日期。语言仓库的变更不会在不知不觉中改变网站。
 
 设计查看器展示的是录制好的映射和原生截图；它不运行视觉模型。已归档的评审仍记录着尚存的视觉差异。购买的 Sketch 素材不会再分发。学校、快递和出行卡片使用仅在浏览器中存在的示例数据；其中的审批不会运行工作流，也不会触发外部操作。
 

scripts/doc-links.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 const root = fileURLToPath(new URL('../', import.meta.url));
 const upstream = 'src/content/upstream/octoscript/';
 const routes = {
-  ...Object.fromEntries(['why-octoscript', 'splash-a2app', 'design-to-app', 'language-profiles', 'component-library'].flatMap(slug => ['en', 'cn'].map(locale => [`src/content/guides/${slug}.${locale}.md`, `${locale === 'cn' ? '/cn' : ''}/docs/${slug}/`]))),
+  ...Object.fromEntries(['octosense-apps', 'why-octoscript', 'splash-a2app', 'design-to-app', 'language-profiles', 'component-library'].flatMap(slug => ['en', 'cn'].map(locale => [`src/content/guides/${slug}.${locale}.md`, `${locale === 'cn' ? '/cn' : ''}/docs/${slug}/`]))),
   ...Object.fromEntries(Object.entries({
   'README.md': '/', 'README.zh-CN.md': '/cn/',
   'docs/README.md': '/docs/', 'docs/README.zh-CN.md': '/cn/docs/',

src/components/AgentTools.astro

@@ -20,5 +20,7 @@ const rows = cn ? [
   <div class="section-heading"><div><span class="eyebrow">06 / THE APP IS THE WORKBENCH</span><h2 id="agent-title">{cn ? '把开发工具放进应用。\n让 Agent 直接参与。' : 'Put the tools in the app.\nLet the agent work directly.'}</h2></div><p>{cn ? '从面向人类的 Studio，到应用内可通过 socket 访问的检查和控制原语。Agent 无需操作 IDE 窗口，就能理解和驱动正在运行的 UI。' : 'From Studio for human developers to inspection and control primitives inside the app, reachable over a socket. An agent can understand and drive the running UI without operating an IDE window.'}</p></div>
   <div class="instrument-panel"><div class="instrument-header"><Icon name="chip" size={20}/><span>app --remote</span><span>127.0.0.1:PORT / HTTP</span></div><ol>{rows.map(([endpoint,title,body],i) => <li><span class="instrument-step">0{i+1}</span><div><h3>{title}</h3><p>{body}</p></div><code>{endpoint}</code></li>)}</ol><div class="instrument-footer">{cn ? '观察 → 操作 → 验证 → 修正 → 再构建' : 'OBSERVE → ACT → VERIFY → REPAIR → REBUILD'}</div></div>
   <p class="story-note">{cn ? '开发实例显式启用仪器。这里的 headless 指不依赖 Studio GUI，视觉验证仍使用真实 GPU；各平台的检查与采集能力以宿主实现为准。' : 'Instrumentation is enabled explicitly for development. Headless means no Studio GUI is needed; visual checks still use the real GPU, with inspection and capture support determined by each host.'}</p>
+  <p class="story-note">{cn ? '这里的 Agent 帮助开发和测试应用。运行时应用 Agent 则由 OctoSense 和 octos 管理，使用用户允许的账户工作区、工具与对话路由。独立 card-host 没有注册 Agent 服务。' : 'These instruments serve a coding agent. Runtime app agents are managed by OctoSense and octos, with permitted account workspaces, tools and conversation routes. Standalone card-host registers no agent services.'}</p>
+  <a class="text-link" href={route(locale, 'docs/octosense-apps/')}>{cn ? '运行应用并追踪它的 Agent' : 'Run an app and follow its agent'}<Icon name="arrow" size={16}/></a>
   <a class="text-link" href={route(locale, 'docs/splash-a2app/')}>{cn ? '阅读语言、仪器与 A2App 的完整关系' : 'Read how language, instruments and A2App fit together'}<Icon name="arrow" size={16}/></a>
 </section>