[JacobStephens2]

Summary

Documents #583's Plan usage viewing and routing, Pass skips and Plan-usage Paused Commands in the user manual, the hand-written site pages and the domain-to-code index. Earlier #583 Tickets had already documented thirdshift plan-usage, Console /plan-usage, Fleet grouping, the report push and the header pill. This PR fills the gaps that remained.

 docs/guide.md
   The Claim › When the Claim ends
+    Released even with work on origin: Paused Command (no agent-failed; needs-triage after an untrusted edit; Security fix keeps agent-failed)
   Plan usage
+    five subscription Harnesses; why opencode and kimi are left out; ~/.thirdshift/plan-usage.json
+    passive wire frames vs official zero-token reads (codex app-server, muse serve, claude auth status)
+    cooldowns, 1h→6h revalidation backoff, which rows are shown
+    #### Routing by Plan usage
+      [harness] routes / max_utilization / allow_credits (Codex credits, agy useG1Credits), [security] routes
+      Setup writes the defaults and asks nothing about them
+      proactive and reactive per-Step routing, clean mid-Step reset, conflict re-merge, Continuation prompt
+      what stays pinned; Built with vs Session models
+    #### When no route has Plan usage
+      Pass skip + banner; Paused Command: Claim, Done vs Needs you, Run notification
   User config (Setup's file)      + routes / max_utilization / security.routes lines, not asked about
   Harness, Model and Effort       + routes replace harness.default when the command names none
   Run notifications               + routed Built with; paused notification under email.unless_merged
   Security runs / Security review + security.routes → harness.routes → harness.default
 site/index.html                   Pass skips, Security review fallback, Harness note, Failure limit
 site/how-it-works/index.html      Pass check, Security review fallback, Failure limit
 site/architecture/index.html      per-Step Router paragraph, Plan usage admission, Claim endings
 docs/code-navigation.md           rows: Plan usage observation · Route selection · Plan-usage Paused Command, Pass skip
                                   Fleet row: Console /plan-usage, jump key p, OpenAPI/parity, CLI args
 site/docs/index.html              regenerated

Evidence

Execution evidence

• Before (refs/remotes/origin/issue-583): the manual has no routing or no-route sections.

  $ git show refs/remotes/origin/issue-583:site/docs/index.html | grep -c 'id="routing-by-plan-usage"'
  0
  $ git show refs/remotes/origin/issue-583:site/docs/index.html | grep -c 'id="when-no-route-has-plan-usage"'
  0
  $ git show refs/remotes/origin/issue-583:docs/guide.md | grep -c 'harness.routes'
  0
  

  After (HEAD):

  routing-by-plan-usage: 1
  when-no-route-has-plan-usage: 1
  harness.routes in manual: 8
  

• npm run docs:check --prefix site exits 0. scripts/affected-tests origin/issue-583 ran npm test --prefix site: # tests 69 # pass 69 # fail 0.
• The same run's cargo test --test share_card --test site_deploy could not build on this machine (error: linker 'cc' not found), so CI must cover it. Those tests read only the home page's meta tags and synthetic fixtures, and this PR leaves both alone.

Visual evidence

Manual, /docs/#plan-usage, desktop 1440×900. The change is prose inside the existing layout, so no responsive layout changed.

Review

The Standards review raised 5 findings and the Spec review raised 2. All 7 are addressed in 4a56117:

• Standards
  • Fixed the route-selection row's test pointer: it named tests/harness_choice.rs and now names the inline tests in src/asks.rs.
  • Added the Paused Command to the architecture page's Claim endings, and beside the full-disk release on the home and how-it-works pages.
  • Fixed the ambiguous "that quota".
  • Replaced "rate limits" with "Plan windows".
  • The code index now names constants instead of copying their values.
• Spec 1
  • Finding: with no routes, a Security session still falls back to harness.default. src/plan_usage/router.rs:116-119 does this, and its own test asserts it.
  • The docs now say so. I left the code alone: this is ADR 0021's long-standing Security review fallback.
• Spec 2
  • Finding: Pass admission refreshes a stale Codex or Muse snapshot (pass_exhaustion calls refresh_for_routing).
  • The architecture and how-it-works pages and the manual's Pass-skip bullet now say so.

Review coverage: both reviewers read every changed file. site/docs/index.html is generated output and both reviewers excluded it after docs:check passed. Both confirmed the exclusion and checked its anchors only.

Unaddressed findings

None.

Security review outcome

No unaddressed introduced findings.

Merge Danger

Door: two-way

Documentation and static site text only. Reverting the commits restores the previous text.

Blast Radius: docs

The manual and site pages could misdescribe routing if #583's behaviour changes before it merges. No code or test changed.

Closes #2185

Built with claude 2.1.322 · claude-opus-5-5 · high