Update development layout docs

[CooperSheroy]

Summary

• refresh the development guide project tree to match the current app/core/CLI/widget SwiftPM layout
• update the new-provider checklist with the current descriptor, app glue, resource, and test locations

Verification

• node Scripts/check-documentation-links.mjs
• checked every newly documented path exists
• git diff --check

[clawsweeper]

Codex review: needs changes before merge. Reviewed July 6, 2026, 11:38 PM ET / 03:38 UTC.

Summary
The PR updates docs/DEVELOPMENT.md with the current SwiftPM layout and a revised new-provider checklist.

Reproducibility: yes. for the docs regression: the PR head checklist omits implementation registration, while current source still requires ProviderImplementationRegistry for app-side provider lookup.

Review metrics: none identified.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🌊 off-meta tidepool
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Add a provider checklist step for Sources/CodexBar/Providers/Shared/ProviderImplementationRegistry.swift.

Risk before merge

• [P1] If merged as-is, contributors following the new-provider checklist could miss the required app implementation registry update and end up with an incomplete provider addition.

Maintainer options:

1. Decide the mitigation before merge
   Keep the docs layout refresh, but add back a checklist step for Sources/CodexBar/Providers/Shared/ProviderImplementationRegistry.swift.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P2] The remaining blocker is a narrow docs repair that can be made mechanically on the PR branch.

Security
Cleared: The diff changes only docs/DEVELOPMENT.md and does not alter code execution, dependencies, secrets, or release automation.

Review findings

• [P2] Restore the provider implementation registration step — docs/DEVELOPMENT.md:110-113

Review details

Best possible solution:

Keep the docs layout refresh, but add back a checklist step for Sources/CodexBar/Providers/Shared/ProviderImplementationRegistry.swift.

Do we have a high-confidence way to reproduce the issue?

Yes for the docs regression: the PR head checklist omits implementation registration, while current source still requires ProviderImplementationRegistry for app-side provider lookup.

Is this the best way to solve the issue?

No; the narrow maintainable fix is to keep the refreshed layout but restore a registration step for the current app implementation registry.

Full review comments:

• [P2] Restore the provider implementation registration step — docs/DEVELOPMENT.md:110-113
  The updated checklist no longer tells contributors to add the app-side implementation to ProviderImplementationRegistry. Current app code still routes ProviderCatalog through that registry, and makeImplementation(for:) is exhaustive over UsageProvider, so a new provider following this checklist will miss a required app registration step.
  Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.9

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 46edb383c0ac.

Label changes

Label changes:

• add P3: This is a low-risk docs-only PR with one provider checklist accuracy issue.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

• P3: This is a low-risk docs-only PR with one provider checklist accuracy issue.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

Acceptance criteria:

• [P1] git diff --check.
• [P1] node Scripts/check-documentation-links.mjs.

What I checked:

• PR diff is docs-only: The proposed branch changes only docs/DEVELOPMENT.md with 23 additions and 17 deletions. (docs/DEVELOPMENT.md:110, 7a3f4f463730)
• Provider checklist omission: The new checklist has descriptor, app glue, resource, and test steps, but no step to register app implementations in ProviderImplementationRegistry. (docs/DEVELOPMENT.md:106, 7a3f4f463730)
• Current app registry requirement: ProviderCatalog delegates app implementation lookup to ProviderImplementationRegistry, and that registry has an exhaustive makeImplementation(for:) switch over every UsageProvider. (Sources/CodexBar/Providers/Shared/ProviderImplementationRegistry.swift:14, 46edb383c0ac)
• Removed checklist step provenance: Current main's existing docs explicitly included Register the implementation in ProviderImplementationRegistry; the PR removes that step while the registry still exists. (docs/DEVELOPMENT.md:106, a83a83fa4131)
• Whitespace check: The proposed docs diff has no git diff --check whitespace errors. (docs/DEVELOPMENT.md, 7a3f4f463730)

Likely related people:

• steipete: Blame and git log --follow show Peter Steinberger authored the current docs/DEVELOPMENT.md provider checklist and the current provider implementation registry in commit a83a83fa. (role: recent area contributor; confidence: medium; commits: a83a83fa4131; files: docs/DEVELOPMENT.md, Sources/CodexBar/Providers/Shared/ProviderImplementationRegistry.swift)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.