Skip to content

[chore] Extract architecture docs / config tables / component inventories out of CLAUDE.md into docs/ #277

@Jason-Vaughan

Description

@Jason-Vaughan

What

CLAUDE.md is 398 lines — large enough that the SessionStart briefing flags it every session ("move architecture docs, config tables, and component inventories to docs/ or .prawduct/artifacts/"). Trim it back to enforced rules + playbook, relocating reference material into docs/.

Why

CLAUDE.md is load-bearing instruction context injected into every session. The longer it is, the more token budget every session pays and the harder the actual rules are to find amid reference tables. Much of its bulk is reference material (API operation tables for PortHub / shared-docs, port-range conventions, component inventories) that belongs in docs/ and can be linked, not inlined.

Scope / suggested approach

  • Keep in CLAUDE.md: the enforced Core/Extension rules, the Prawduct playbook/session discipline, and short pointers.
  • Move to docs/: the PortHub API operation tables + port-range conventions, the Shared Documents API tables, and any component-inventory / config-table material.
  • Replace moved sections with a one-line link to the docs/ page.
  • Verify nothing that is an enforced behavioral rule gets demoted to a doc (rules must stay in CLAUDE.md so they keep overriding default behavior).

Notes

  • This is a design decision (what is a rule vs reference), not a mechanical move — deserves its own session/chunk, not an end-of-session sweep.
  • Surfaced during a /janitor sweep on 2026-05-30 (Artifact Fitness / Docs theme).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions