docs: consolidate root build-guide and planning docs into docs/ tree#27
Merged
Conversation
Move the flat root-level documentation into the existing docs/ tree to
declutter the repository root. The canonical architecture spec stays at
the root (packaging-critical: referenced by pyproject.toml + MANIFEST.in,
ships in the sdist).
- docs/build-guides/ <- all 11 BUILDGUIDE_phoenix_v1_phase*.md (+ new index)
- docs/planning/ <- perception-harness plan v1, roadmap, phase-13
design decisions; v0 plan under planning/archive/
- README: drop the Phase 0 build-guide link (build guides are no longer
advertised on the main README); repoint perception-plan links; add a
docs/ hub link.
- docs/README.md rewritten as the documentation hub.
All moves are git renames (history preserved). Build guides now live under
the MANIFEST.in `prune docs` rule, so they no longer ship in the sdist
(intended: they are internal development records, not user docs).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reviewer's GuideRestructures root-level documentation into the existing docs/ tree, keeping the architecture spec at the repo root, updating the main README and docs README to route users through a docs hub, and adding a build-guides index while ensuring build guides are treated as internal records that no longer ship in the sdist. Flow diagram for user navigation via the new docs hubflowchart TD
User["User"] --> RootReadme["README.md (repo_root)"]
RootReadme --> DocsHubLink["Link to docs/README.md"]
DocsHubLink --> DocsHub["docs/README.md (documentation_hub)"]
DocsHub --> DistGuide["docs/distribution/README.md (install_run)"]
DocsHub --> ReproGuide["docs/reproducibility/README.md (reproducibility)"]
DocsHub --> Planning["docs/planning/ (plans_and_decisions)"]
DocsHub --> BuildGuides["docs/build-guides/README.md (internal_build_guides)"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Fix the relocated build-guide link
After this file moved into docs/planning/, this relative link now resolves to docs/planning/BUILDGUIDE_phoenix_v1_phase13_cognition_mcp_client.md, but the guide was moved to docs/build-guides/BUILDGUIDE_phoenix_v1_phase13_cognition_mcp_client.md. Anyone following the roadmap companion-doc link from GitHub or a Markdown link checker will hit a missing page; update this link to ../build-guides/BUILDGUIDE_phoenix_v1_phase13_cognition_mcp_client.md.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
nah414
added a commit
that referenced
this pull request
Jun 9, 2026
* @ docs(agents): add CLAUDE.md auto-loaded agent operating rules Encode the maintainer's working rules so every Claude Code session in this repo picks them up automatically (CLAUDE.md auto-loads per-repo). - CLAUDE.md (root): concise rule set, points to the detailed doc. - docs/AGENT_WORKFLOW.md: long-form rules, halt list, branch/commit conventions, reporting format, Windows/PowerShell notes, rationale. - docs/README.md: link the new workflow doc from the docs hub. Rules optimize for remote phone-driven sessions via Dispatch: no interactive pickers (plain-text questions only), autonomous reversible defaults, halt only for destructive/irreversible actions, feature branch only, plan-but-do-not-block, test before handing back. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> @ * @ docs(agents): forbid skipping git hooks / signing as a top-level rule Add an explicit short-form rule (new rule 5) in CLAUDE.md: never use --no-verify, never disable/skip/bypass pre-commit or commit-msg hooks or commit signing unless the maintainer explicitly asks; fix the underlying issue instead. Mirrors and strengthens AGENT_WORKFLOW.md section 4. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> @ * @ docs(agents): post-reorg path fixes + PR-consolidation rule Rebased onto current main (post #26/#27 docs reorg). Adjust for the new docs/ tree and capture the maintainer's PR-cadence preference. - CLAUDE.md: repoint build-guide reference from the old repo-root BUILDGUIDE_*.md files to docs/build-guides/ (moved by #27). - docs/README.md: re-add the AGENT_WORKFLOW.md pointer into the reorganized "Internal development records" section (the old pre-reorg edit was dropped during rebase). - CLAUDE.md + AGENT_WORKFLOW.md: add a new rule (short form rule 5; detail in AGENT_WORKFLOW.md section 4) — consolidate work, at most one PR per work-session/batch, branches may accumulate commits and sit for days, never open a PR proactively, default posture is keep-on-branch. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> @ * @ docs(agents): record mobile-Dispatch working method + 2026-06-09 session log Note in CLAUDE.md (not the README) that this repo is primarily driven via mobile Dispatch (Adam running Claude Code sessions from his phone while the desktop runs), and log today's session: README trim (#26 merged), docs/ reorg (#27 merged), auto-capture wiring (phase-13.x.9, parked), these agent rules, and the Step 5c cognition training/eval harness (parked; lightgbm 4.6.0 kept for local runs). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> @ --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Structural cleanup of the repository root: the flat pile of build-guide and
planning docs moves into the existing
docs/tree. No content edits —every doc move is a
git mvrename (full history preserved). OnlyREADME.mdand
docs/README.mdare edited (link/path fixes), plus two new index files.Approved scope (keep architecture spec at root, keep build-guide filenames
as-is, single
docs/planning/folder, build guides may stop shipping in thesdist, and do not advertise build guides on the main README).
Before / after (root-level docs)
Before — 16 docs flat at root:
After — root keeps only the canonical front-matter; everything else under
docs/:README link changes
longer surfaced on the main README. They live under
docs/build-guides/,reachable via the docs hub.
docs/hub link.docs/planning/, v0 ->docs/planning/archive/). The architecture-spec link is unchanged (filestays at root).
Notes / intended side effects
PHOENIX_ARCHITECTURE_v1.mddeliberately stays at root — it isreferenced by
pyproject.toml(DocumentationURL) andMANIFEST.in(
include, ships in the sdist). No packaging files needed changes.MANIFEST.in'sprune docsrule, so theyno longer ship in the source distribution (intended — they are internal
development records, not user docs).
Authoritative location: C:\Phoenix\...headers inside the moved docsare prose (not links) and were left as-is; they can be refreshed in a
follow-up if desired.
🤖 Generated with Claude Code
Summary by Sourcery
Consolidate documentation into a docs hub, moving build guides and planning documents under the docs tree and updating links accordingly.
Documentation: