docs(backlog): record unowned 1.0 criteria and fix the loopback URL claim

[joelst]

Audits docs/BACKLOG.md against the seven 1.0 release criteria in RELEASE_ROADMAP.md and the post-0.7.0 workstreams in docs/PRODUCT_PLAN.md. Six of the seven criteria had work that appeared in none of the three documents, so the 1.0 bar could not be checked against anything.

New section: 1.0 release criteria — unowned work

For the criteria with no topical home elsewhere in the backlog:

• Least-privilege capability model (criterion 1) — src-tauri/capabilities/default.json has never been audited against what the app invokes. It appeared in PRODUCT_PLAN only as a source anchor.
• Renderer/sidecar boundary security suite (criterion 1) — no tests assert what the renderer may ask the sidecar to do.
• Deterministic cancellation and timeout (criterion 2) — the decision exists in PRODUCT_PLAN's rubber-duck table; no item tracked making it true across every request type.
• Multi-endpoint manager (criterion 2) — a hard 1.0 requirement in the roadmap, filed here under Future features (unscheduled). Recorded as a contradiction to settle, not a task.
• Endpoint health history (criterion 4) — nothing retains health over time, so "robust recovery and health checks" cannot be evidenced.
• UX maturity (criterion 5) — named in the roadmap and nowhere else; as written it cannot be called done or not done.
• Admin guide and operator runbook (criterion 7) — neither exists. USER_GUIDE's troubleshooting table is user-facing, not an operator runbook.

Shipping integrity

• The updater has never resolved a manifest. With 0.7.0 published as a prerelease, both releases/latest and releases/latest/download/latest.json return 404 — verified against the live repo. Discovery → signature check → download has never executed against a real release. Shipping a stable release is what exercises it.
• The Apple Developer ID question needs a decision — notarize, or declare macOS permanently evaluation-only. Distinct from the upstream SDK dylib quarantine already tracked under Dependencies.

Test coverage

• No component or E2E layer exists at all — tests/ holds one PowerShell file for Azure signing. Unit and contract are strong; the criterion names four layers.
• Coverage allowlist blind spots — the 43-file allowlist at 97/94/84/95 excludes src/lib/sdk.ts and sidecar/foundry-sidecar.js, both core paths.
• +page.svelte was recorded as ~444 KB; it is 472 KB / 11,221 lines. That number is the progress measure for the extraction strategy, so it should be accurate.

Stale claim corrected

Three places still said the client URL is always 127.0.0.1 — README.md, docs/USER_GUIDE.md, and the renderSnippet JSDoc in src/lib/integrations.ts. #117 contradicted this one line away in the same USER_GUIDE table: WSL2 clients in default NAT mode cannot reach it.

Verification

• npm run verify:markdown-links — 137 links across 31 files
• npm run check — 410 files, 0 errors (1 pre-existing a11y warning in +page.svelte)
• npm test — 1100/1100 across 45 files

Documentation and one JSDoc comment; no behavior change. Changeset has empty frontmatter, so it bumps nothing.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Unresolved review comments remain on URL guidance and backlog accuracy.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This documentation-only PR audits 1.0 release gaps and corrects client URL guidance.

Changes:

• Adds release, shipping, and test-coverage backlog items.
• Clarifies loopback and WSL2 endpoint guidance.
• Adds an empty changeset with no version bump.

File summaries

File	Summary
src/lib/integrations.ts	Clarifies endpoint URL behavior in JSDoc.
README.md	Updates client URL guidance.
docs/USER_GUIDE.md	Documents endpoint and WSL2 networking behavior.
docs/BACKLOG.md	Records 1.0 criteria, shipping, and testing gaps.
.changeset/backlog-1-0-gaps.md	Records the documentation-only changeset.

Review details

Suppressed comments (4)

docs/BACKLOG.md:34

• src/lib/runtime-capability.test.ts:5-33 already checks several high-risk permissions, and FLINT_DESIGN_SPEC.md:147 documents the capability model as hardened. The open work may be a complete permission-to-use audit, but “has never been audited” is too strong; scope this item to the missing comprehensive audit.

- [ ] **Least-privilege capability model** (criterion 1) — `src-tauri/capabilities/default.json`
      has never been audited against what the app actually invokes. Enumerate the permissions
      the renderer genuinely needs, remove the rest, and record why each survivor is required.

docs/BACKLOG.md:30

• The intro says every entry has no corresponding item anywhere else in BACKLOG, but the multi-endpoint entry below is explicitly backed by the existing Full endpoint scheduler item at docs/BACKLOG.md:258-260. Since this is a contradiction to resolve rather than unowned work, broaden the section scope (or exclude this entry) so the audit does not misclassify already-tracked work.

[RELEASE_ROADMAP.md](../RELEASE_ROADMAP.md) states the seven criteria for 1.0. These are
the ones with no item anywhere else in this file and no workstream in
[PRODUCT_PLAN.md](./PRODUCT_PLAN.md). They are unscoped: size them before committing to a
1.0 date. Criterion 3 (testing) is covered under [Test coverage](#test-coverage).

docs/USER_GUIDE.md:36

• The correction still narrows the exception to WSL2, but a service configured with a specific non-loopback bind is another supported case: formatPublicEndpoint returns that configured address and the resulting state.endpoint is what snippets use. Mention that behavior here so LAN clients are not directed to 127.0.0.1.

   - Client URL is usually **`http://127.0.0.1:<port>/v1`** (loopback) — clients inside WSL2 are the exception, see [Network bind vs client URL](#network-bind-vs-client-url).

docs/USER_GUIDE.md:36

• This describes all WSL2 clients as the exception, but mirrored networking intentionally lets WSL2 use the ordinary loopback URL. Only WSL2's default NAT mode needs the alternate setup, as the linked section and the table below explain.

   - Client URL is usually **`http://127.0.0.1:<port>/v1`** (loopback) — clients inside WSL2 are the exception, see [Network bind vs client URL](#network-bind-vs-client-url).

• Files reviewed: 5/5 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

Remaining documentation inconsistencies and stale or contradictory backlog details must be corrected.

Review details

Suppressed comments (4)

Previously missed (1) — in code that hasn't changed since the last review.

docs/BACKLOG.md:28

• This says the listed criteria have no item anywhere else in BACKLOG, but the existing Future features (unscheduled) section already contains Full endpoint scheduler at line 257, which is the related multi-endpoint work. The new bullet itself identifies that contradiction, so scope this sentence to criteria with no owned or scheduled item (or explain why that existing item does not count) to avoid contradicting the section.

README.md:155

• Please update the remaining user-visible URL claims as part of this cleanup. src/routes/+page.svelte still tells users at 4389, 6203, 7637, 8258, 8292, and 8347 that the client endpoint stays on loopback, while docs/DEVELOPMENT.md:96 says sharedEndpoint is always 127.0.0.1. Those are false for WSL2 NAT/manual host access and for a specific non-loopback bind (formatPublicEndpoint preserves that address), so the app/help/developer docs will still contradict this corrected README sentence.

Client URL for tools is usually **`http://127.0.0.1:<port>/v1`** (loopback); tools running inside WSL2 in its default NAT mode cannot reach that address and need **Settings → Network → WSL clients**. The **bind address** in Settings controls what the service *listens* on and may differ (e.g. `0.0.0.0` for LAN). Use **Apply & restart** after changing bind/port.

docs/BACKLOG.md:103

• The current file ends at line 12,108 (the closing </style> is at that line), so the recorded 11,221-line baseline is already stale. Because this number is explicitly the extraction progress measure, please update it to 12,108 and recheck the byte count before relying on it.

- [ ] **`+page.svelte` is untested** and holds most of the app (472 KB, 12,108 lines,
      `@ts-nocheck`). Keep extracting pure logic into `src/lib/*.ts` with tests rather than
      testing the component. The line count is the progress measure for that extraction —
      keep it current.

docs/USER_GUIDE.md:36

• The quick-start wording classifies all WSL2 clients as the exception, but the section below documents that mirrored WSL2 shares the host loopback and still uses http://127.0.0.1. Please scope this to WSL2 clients in default NAT mode so mirrored-networking users are not told that their normal URL is an exception.

   - Client URL is usually **`http://127.0.0.1:<port>/v1`** (loopback) — clients inside WSL2 are the exception, see [Network bind vs client URL](#network-bind-vs-client-url).

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Outstanding documentation inconsistencies must be corrected before approval.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (6)

Previously missed (2) — in code that hasn't changed since the last review.

README.md:155

• The detailed paragraph is corrected here, but the summary table at README.md:27 still tells users to point Continue, Cline, OpenAI SDKs, and all other clients at 127.0.0.1 without a WSL2 qualification. In default NAT mode that URL is unreachable from WSL, so please qualify that row or link it to the WSL clients instructions; otherwise the README still contains the unqualified claim this PR is meant to remove.
  docs/USER_GUIDE.md:36
• This wording is broader than the actual exception: the Network section below says WSL2 clients in mirrored mode can use the usual loopback URL, so not all clients inside WSL2 are exceptions. Please qualify this as “WSL2 clients in default NAT mode” to avoid contradicting the guidance at lines 90–99.

docs/BACKLOG.md:100

• The progress count is stale: src/routes/+page.svelte currently has 12,110 lines, not 12,108. Since the following sentence explicitly makes this count the extraction progress measure, keep the documented number synchronized with the file.

- [ ] **`+page.svelte` is untested** and holds most of the app (472 KB, 12,108 lines,

docs/BACKLOG.md:46

• This section says every entry has no item elsewhere in BACKLOG.md, but the existing Full endpoint scheduler item is already listed under Future features at lines 257–259. The actual gap here is conflicting ownership/priority between that item and the roadmap; label it as such or move the resolution note next to the existing item so the new “unowned work” section does not duplicate a backlog item.

- [ ] **Multi-endpoint manager is filed as unscheduled** (criterion 2) — the roadmap makes it a
      1.0 requirement; **Full endpoint scheduler** under *Future features* says "not yet started,
      no version assigned." One of the two is wrong. Resolve it deliberately: either schedule the
      manager or drop it from the 1.0 bar.

docs/BACKLOG.md:30

• The new section accounts for criteria 1, 2, 4, 5, and 7; it explicitly says criterion 3 is covered by Test coverage, while criterion 6 already has integration work in PRODUCT_PLAN.md and the existing backlog. That is five criteria without a topical home, not six as stated in the PR description. Please reconcile the count or explain that “six” refers to missing sub-items rather than criteria, so this audit is internally verifiable.

[RELEASE_ROADMAP.md](../RELEASE_ROADMAP.md) states the seven criteria for 1.0. These are
the ones with no item anywhere else in this file and no workstream in
[PRODUCT_PLAN.md](./PRODUCT_PLAN.md). They are unscoped: size them before committing to a
1.0 date. Criterion 3 (testing) is covered under [Test coverage](#test-coverage).

src/routes/+page.svelte:8261

• The new endpoint guidance still leaves a conflicting user-facing message in +page.svelte:4389: the tray notification says the endpoint is 127.0.0.1 without mentioning the WSL2 NAT exception. A WSL user following that notification can still copy an unreachable URL; update the notification to point to the WSL clients panel or qualify the URL consistently.

              <strong>Client URL</strong> (what Integrations and this app use) is usually loopback:
              <code>http://127.0.0.1:&lt;port&gt;/v1</code>.
              WSL2 clients in default NAT mode use the Windows host address from
              <strong>Settings → Network → WSL clients</strong> instead.

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Resolve the remaining URL guidance issues and reconcile the backlog metric, accounting, and section wording.

Review details

Suppressed comments (5)

README.md:155

• The overview table near the top of this same README still tells users to point all clients at http://127.0.0.1:<port>/v1 (line 27). WSL2 NAT clients cannot reach that address, so the stale-claim correction remains incomplete; qualify that row or link it to Settings → Network → WSL clients as well.

Client URL for tools is usually **`http://127.0.0.1:<port>/v1`** (loopback); tools running inside WSL2 in its default NAT mode cannot reach that address and need **Settings → Network → WSL clients**. The **bind address** in Settings controls what the service *listens* on and may differ (e.g. `0.0.0.0` for LAN). Use **Apply & restart** after changing bind/port.

docs/BACKLOG.md:100

• The new progress metric is off: the current +page.svelte ends at line 12,110 (</style>), so this entry's 12,108-line count is stale (and also does not match the PR description's 11,221). Because the entry explicitly uses the line count to measure extraction progress, please reconcile it with the actual file count.

- [ ] **`+page.svelte` is untested** and holds most of the app (472 KB, 12,108 lines,

docs/BACKLOG.md:46

• The section intro says every item has no item elsewhere in BACKLOG.md, but this same file already lists Full endpoint scheduler at lines 257-259. This bullet is useful as a 1.0 scheduling contradiction, but reword the intro or this item so the document distinguishes “unowned” from “already listed but unscheduled.”

- [ ] **Multi-endpoint manager is filed as unscheduled** (criterion 2) — the roadmap makes it a
      1.0 requirement; **Full endpoint scheduler** under *Future features* says "not yet started,
      no version assigned." One of the two is wrong. Resolve it deliberately: either schedule the
      manager or drop it from the 1.0 bar.

docs/BACKLOG.md:30

• The PR description says six of the seven criteria were unowned, but this section accounts for only criteria 1, 2, 4, 5, and 7: it explicitly points criterion 3 to the existing Test coverage section, while the existing Endpoint / agent compatibility items cover criterion 6 (lines 144–159). Please reconcile the count in the PR description with the backlog's own accounting.

[RELEASE_ROADMAP.md](../RELEASE_ROADMAP.md) states the seven criteria for 1.0. These are
the ones with no item anywhere else in this file and no workstream in
[PRODUCT_PLAN.md](./PRODUCT_PLAN.md). They are unscoped: size them before committing to a
1.0 date. Criterion 3 (testing) is covered under [Test coverage](#test-coverage).

docs/USER_GUIDE.md:36

• This exception is too broad: WSL2 mirrored networking is explicitly supported, and mirrored clients continue using 127.0.0.1. Only WSL2's default NAT mode needs the alternate Windows-host URL; qualify this quick-start text so it does not contradict the detailed WSL guidance below.

   - Client URL is usually **`http://127.0.0.1:<port>/v1`** (loopback) — clients inside WSL2 are the exception, see [Network bind vs client URL](#network-bind-vs-client-url).

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite