docs: api: cut to the wire contract

cell/shell/apps-page.js

@@ -1,4 +1,4 @@
-// The Apps page (`/apps`; docs/api.md, The shell): every fragment in the
+// The Apps page (`/apps`): every fragment in the
 // person's list but their chats, agents and skills (apps, brains, a kind
 // this page does not know), each with what they may change of it here, as
 // the server says it is:

cell/shell/launcher.js

@@ -22,7 +22,7 @@
 // the person gives the middle column another view (a chat, settings,
 // Back), the launch changes nothing on screen: its message is still sent,
 // and one not sent is a notice, its words and files waiting in the
-// launcher's next opening (docs/api.md, The launcher).
+// launcher's next opening.
 
 import { icon } from "./icons.js";
 

cell/src/levers.rs

@@ -1,4 +1,4 @@
-//! The test levers, `/api/test/*` (docs/api.md, `FRAGMENT_TEST_SECRET`):
+//! The test levers, `/api/test/*` (docs/api.md, Test levers):
 //! the router sends a request here only once it has checked the fleet's
 //! test secret is set and that the request carries it
 //! (`fragment_core::levers`); to anyone else they are no route.

cell/src/ops.rs

@@ -420,7 +420,7 @@ impl FragmentCell {
 
     /// `POST /api/test/fragment {fragment, op, …}`, the router's, on fleets
     /// with test hooks only: the levers the e2e pulls on one fragment
-    /// (docs/api.md, `FRAGMENT_TEST_SECRET`).
+    /// (docs/api.md, Test levers).
     pub(crate) async fn test_fragment(&self, body: &Value) -> CellResult<Value> {
         assert!(self.cfg.test_hooks, "the route answers only on fleets with test hooks");
         if body["op"] == "ended" {

crates/core/src/levers.rs

@@ -1,4 +1,4 @@
-//! Test levers (docs/api.md, `FRAGMENT_TEST_SECRET`; docs/secrets.md): the
+//! Test levers (docs/api.md, Test levers; docs/secrets.md): the
 //! `/api/test/*` routes the e2e pulls, and the sign-in of its people,
 //! exist only on a fleet given a test secret, and answer only a request
 //! that carries it. A local fleet (dev's and the e2e's, under `wrangler

crates/e2e/src/lanes/shell.rs

@@ -5252,7 +5252,7 @@ fn say_in(s: &Suite, b: &mut Browser, page: &Page, host: &str, text: &str) -> bo
     s.eventually(std::time::Duration::from_secs(30), || b.eval_in_frame(page, host, &typed).ok() == Some(Value::Bool(true)))
 }
 
-/// Unread (docs/api.md, The shell): a chat not open counts on its row what
+/// Unread (docs/api.md, Control API): a chat not open counts on its row what
 /// came since its person saw it, as their list does; opening it marks it
 /// seen, here and in their list; and the open chat counts nothing as its
 /// messages come. The first agent's chat, while the Reader's is open.
@@ -5294,7 +5294,7 @@ fn unread_ui(s: &mut Suite, api: &Api, b: &mut Browser, page: &Page, me: &Person
     Ok(())
 }
 
-/// A new chat (docs/api.md, The shell, the launcher): from the Reader's
+/// A new chat: from the Reader's
 /// chat, the launcher's Enter makes a chat with the person's one agent
 /// (not the open chat's), labelled beside its own (`<first>-chat-2`), the
 /// words posted whole as its first message: one record though the first
@@ -5847,7 +5847,7 @@ fn fresh_shown(b: &mut Browser, page: &Page, before: &[String]) -> Option<String
     (!shown.is_empty() && !before.contains(&shown)).then_some(shown)
 }
 
-/// The launcher as a person uses it (docs/api.md, The launcher). Its input
+/// The launcher as a person uses it. Its input
 /// is one line at rest and as words are typed; Shift+Enter is a new line,
 /// which it grows to, and a long prompt grows it to 200 px, then it
 /// scrolls. Files dropped on it or pasted into it are chips under its words
@@ -6687,7 +6687,7 @@ fn apps_sharing_refresh_ui(s: &mut Suite, b: &mut Browser, page: &Page, app: &st
     Ok(())
 }
 
-/// The Apps page (docs/api.md, The shell; #587), from the sidebar's Apps:
+/// The Apps page (#587), from the sidebar's Apps:
 /// the owner's app listed (no chat or skills), with its card and who has
 /// access; a kind this build does not know is listed as Other; its Dock
 /// switch takes it off the dock and back, moving only as the list does;

crates/e2e/src/lanes/sync.rs

@@ -153,7 +153,7 @@ pub fn folder_sync(s: &mut Suite, api: &Api) -> Result<()> {
     quiet_poll(s, api)
 }
 
-/// The poll backstop (docs/api.md, `FRAGMENT_POLL_INTERVAL_S`): a fragment
+/// The poll backstop (`FRAGMENT_POLL_INTERVAL_S`, cell/src/config.rs): a fragment
 /// whose pins may lag its repo (a storage token was minted for it in the
 /// last day) is polled every interval, so an editor's push through
 /// code.storage syncs within it; one nothing touches is never polled, its

crates/proto/src/computer.rs

@@ -383,7 +383,7 @@ pub struct ComputerView {
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub notices: Vec<ComputerNotice>,
     /// Its agents, in the order it took them: its owner's first is first
-    /// (the shell's one agent: docs/api.md, The shell).
+    /// (the shell's main agent).
     pub agents: Vec<ComputerAgent>,
     /// Its own origin, where its ports are served.
     pub origin: String,

crates/templates/src/lib.rs

@@ -141,19 +141,19 @@ const SHELL_PUBLISHED: [(&str, &str); 47] = [
     ("icons.js", "text/javascript; charset=utf-8"),
     // an app's own icon in the dock, and the sheet that makes one (docs/api.md, Icons)
     ("app-icon.js", "text/javascript; charset=utf-8"),
-    // the Apps page: each app's dock, card, icon and who has access (docs/api.md, The shell)
+    // the Apps page: each app's dock, card, icon and who has access
     ("apps-page.js", "text/javascript; charset=utf-8"),
     ("activity.js", "text/javascript; charset=utf-8"),
     ("fragment-title.js", "text/javascript; charset=utf-8"),
     ("tooltips.js", "text/javascript; charset=utf-8"),
     // Settings' Billing: a seat, credit, an org (docs/billing.md)
     ("billing.js", "text/javascript; charset=utf-8"),
-    // the launcher: ⌘K, to start a chat or find one again (docs/api.md, The launcher)
+    // the launcher: ⌘K, to start a chat or find one again
     ("settings.js", "text/javascript; charset=utf-8"),
     ("chat-list.js", "text/javascript; charset=utf-8"),
     // the Session Archive under the chats (templates/sessions/README.md)
     ("session-archive.js", "text/javascript; charset=utf-8"),
-    // delegation threads: a line each over the chat an agent asked from (docs/api.md, The shell)
+    // delegation threads: a line each over the chat an agent asked from
     ("threads.js", "text/javascript; charset=utf-8"),
     ("session-refresh.js", "text/javascript; charset=utf-8"),
     ("onboarding.js", "text/javascript; charset=utf-8"),