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 maintainer review before merge. Reviewed July 9, 2026, 4:58 AM ET / 08:58 UTC.

Summary
This PR updates docs/DEVELOPMENT.md to refresh the project tree and new-provider checklist for the current app/core/CLI/widget SwiftPM layout.

Reproducibility: not applicable. this is a documentation-only PR. I verified the documented paths and registry references by source inspection instead of reproducing runtime behavior.

Review metrics: 1 noteworthy metric.

• Changed surface: 1 docs file changed; 31 added, 18 removed. The patch is limited to documentation, so runtime proof and merge-risk labels are not needed.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
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:

• none.

Next step before merge

• No automated repair remains; the prior checklist gap is fixed and the remaining action is normal maintainer review.

Security
Cleared: The diff is documentation-only and does not touch code execution, dependencies, secrets, packaging, or release automation.

Review details

Best possible solution:

Land the docs update after normal maintainer review so docs/DEVELOPMENT.md stays aligned with docs/provider.md and the current SwiftPM paths.

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

Not applicable; this is a documentation-only PR. I verified the documented paths and registry references by source inspection instead of reproducing runtime behavior.

Is this the best way to solve the issue?

Yes; linking to the canonical provider guide and keeping the short checklist in sync is the narrowest maintainable docs fix.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 7f5ef1705577.

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P3: This is a low-risk documentation maintenance PR with limited user-facing urgency.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

What I checked:

• Changed surface: The PR merge diff modifies only docs/DEVELOPMENT.md. (docs/DEVELOPMENT.md, fcc0b336acd8)
• Current main still has stale layout docs: Current main still lists the older project tree and shorter provider checklist, so the requested docs update is not already implemented on main. (docs/DEVELOPMENT.md:84, 7f5ef1705577)
• Prior review blocker fixed: The current PR head includes the app-side implementation registry step at Sources/CodexBar/Providers/Shared/ProviderImplementationRegistry.swift. (docs/DEVELOPMENT.md:117, fcc0b336acd8)
• Canonical provider guide matches the checklist: docs/provider.md names ProviderDescriptorRegistry and ProviderImplementationRegistry as the bootstrap boundary and includes matching add-provider steps. (docs/provider.md:43, 7f5ef1705577)
• Area history: The existing docs/DEVELOPMENT.md project-structure section on main traces to the latest release-docs commit authored by Peter Steinberger. (docs/DEVELOPMENT.md:79, a83a83fa4131)

Likely related people:

• steipete: The current main docs/DEVELOPMENT.md section and adjacent provider documentation history trace to Peter Steinberger’s recent release-docs commit, and the PR branch’s follow-up checklist repair was also authored by him. (role: recent area contributor; confidence: high; commits: a83a83fa4131, 2faeb2be8cdf; files: docs/DEVELOPMENT.md, docs/provider.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.

Review history (1 earlier review cycle)

• reviewed 2026-07-07T03:38:13.550Z sha 7a3f4f4 :: needs changes before merge. :: [P2] Restore the provider implementation registration step

[steipete]

Maintainer proof for exact head fcc0b336acd82c420e1a99e7389d0f9b162b7964:

• Deep source-to-doc review found two correctness gaps in the proposed provider checklist: every provider requires an app-side ProviderImplementation, and the exhaustive ProviderImplementationRegistry switch must be updated. The repaired checklist states both requirements and makes parser/settings/status pieces conditional on the provider's actual needs.
• The project tree is explicitly non-exhaustive, includes the packaged WidgetExtension, and describes the macOS test suite as XCTest plus Swift Testing. It links to the canonical provider authoring guide to reduce future drift.
• Exact documentation gates pass: 157 local links, docs-list generation, docs/llms.txt freshness, every newly documented path exists, and git diff --check.
• Repository gates pass: make check, all 49 make test shards, and clean autoreview.
• Runtime/UI proof is not applicable to this docs-only workflow correction; source-path, registry-exhaustiveness, generated-doc, and link validation are the direct behavior proof.
• Public Model Identifier Gate: PASS. Dependency freshness: unchanged; no dependency added or updated.

Thanks for refreshing the development layout, @CooperSheroy!