Organize package docs as internal

[justin808]

Summary

• move package-maintainer docs under internal/docs/ and contributor playbooks under internal/docs/contributor-info/
• keep docs/README.md as the small public-doc boundary note that sends application docs downstream to shakacode/react_on_rails
• update README, agent workflow docs, skill metadata, and internal relative links for the new paths

Verification

• yarn (installed dependencies after the first validate attempt reported missing tsc)
• .agents/bin/validate
• git diff --cached --check
• markdown relative-link check: checked 42 markdown files; no missing relative links

Notes

• Docs-only reorganization; no changelog entry.

[coderabbitai]

Warning

Review limit reached

@justin808, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e72bc2e2-2d57-4314-810b-3b568ee17a6f

📥 Commits

Reviewing files that changed from the base of the PR and between bd5b61f and 512d5a4.

📒 Files selected for processing (39)

• .agents/skills/README.md
• .agents/skills/react-upgrade/SKILL.md
• .agents/skills/rsc-triage/SKILL.md
• .agents/workflows/pr-processing.md
• AGENTS.md
• CLAUDE.md
• README.md
• docs/README.md
• docs/consuming-unreleased-builds.md
• docs/critical-resource-hints.md
• docs/eliminate-react-fork.md
• docs/internal/css-to-component-association-approaches.md
• docs/internal/rsc-webpack-plugin-known-problems.md
• docs/open-rsc-work-status.md
• docs/rails-system-spec-streaming-rsc.md
• docs/releasing.md
• docs/repo-improvement-audit-2026-06.md
• docs/rsc-static-islands-diagnostics.md
• docs/versioning.md
• internal/docs/README.md
• internal/docs/agent-workflows/README.md
• internal/docs/agent-workflows/agent-coordination-backend.md
• internal/docs/agent-workflows/agent-pr-batch-skills.md
• internal/docs/agent-workflows/agent-workflow-adoption.md
• internal/docs/agent-workflows/multi-batch-operations.md
• internal/docs/consuming-unreleased-builds.md
• internal/docs/critical-resource-hints.md
• internal/docs/css-to-component-association-approaches.md
• internal/docs/eliminate-react-fork.md
• internal/docs/open-rsc-work-status.md
• internal/docs/rails-system-spec-streaming-rsc.md
• internal/docs/releasing.md
• internal/docs/repo-improvement-audit-2026-06.md
• internal/docs/rsc-static-islands-diagnostics.md
• internal/docs/rsc-webpack-plugin-known-problems.md
• internal/docs/versioning.md
• patches/archive/abanoubghadban-react/README.md
• scripts/react-upgrade/README.md
• tests/webpack-plugin/plugin-integration.test.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jg-codex/internal-docs-organization

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Review Summary

Reviewed this docs-only reorganization (move package-maintainer docs under docs/internal/, contributor playbooks under docs/internal/contributor-info/, plus new boundary READMEs).

No issues found. I independently verified:

• No dangling references to any old path (docs/releasing.md, docs/versioning.md, docs/eliminate-react-fork.md, docs/open-rsc-work-status.md, docs/critical-resource-hints.md, docs/consuming-unreleased-builds.md, docs/rsc-static-islands-diagnostics.md, docs/rails-system-spec-streaming-rsc.md, docs/repo-improvement-audit-2026-06.md, docs/rsc-webpack-plugin-known-problems.md, internal/contributor-info/*) anywhere in the repo at HEAD.
• Every relative markdown link touched by the move resolves correctly, including the trickiest case: docs/internal/contributor-info/*.md moved one directory deeper than internal/contributor-info/*.md, so repo-root references correctly went from ../../X to ../../../X (verified against AGENTS.md, .agents/skills/*, .agents/workflows/*, etc.) — no off-by-one depth errors.
• docs/internal/README.md's Contents list enumerates exactly the 11 files present in docs/internal/ (excluding itself) — no omissions or stale entries.
• docs/internal/css-to-component-association-approaches.md's links to ../../src/webpack/RSCWebpackPlugin.ts and ../../src/flight-stylesheet-hints.ts correctly account for the extra directory depth.

This is a clean, mechanically careful rename/link-update pass. No correctness, security, or performance concerns — nothing to flag.

[claude]

Review

This is a clean docs-only reorganization: docs/*.md (and docs/internal/*.md, internal/contributor-info/*.md) moved under internal/docs/ (with internal/docs/contributor-info/), leaving docs/README.md as a small public/internal boundary note. I verified:

• Relative link integrity: every relative markdown link in the moved/new files (internal/docs/**, docs/README.md, internal/docs/contributor-info/**) resolves correctly at the new nesting depth (checked path resolution by hand, e.g. the ../../src/... links in css-to-component-association-approaches.md and the ../../../AGENTS.md/.agents/... links in contributor-info/*.md).
• No stale references: repo-wide search for old paths (docs/releasing.md, docs/versioning.md, docs/eliminate-react-fork.md, docs/internal/..., internal/contributor-info/..., etc.) across .md, AGENTS.md, CLAUDE.md, skill files, and test comments turned up nothing left over — every reference was updated to internal/docs/....
• Index consistency: the new internal/docs/README.md contents list matches exactly the files that actually live under internal/docs/.

No correctness, security, or performance issues — nothing to flag. Nice mechanical execution of a docs move with all cross-references updated consistently.

[justin808]

if all docs internal are for contributors why the subdirectory for contributors?

[justin808]

Review-fix evidence for the latest push (75cbace):

• Answered the maintainer layout question by renaming the redundant internal/docs/contributor-info/ subtree to internal/docs/agent-workflows/.
• Updated AGENTS, workflow docs, skill README links, and internal docs navigation to the new path.
• Swept for stale contributor-info references; none remain.
• Read-only subagent review found no blockers and confirmed the rename better distinguishes agent/operator procedures from package-maintainer docs.

Local validation:

• yarn build
• yarn test
• git diff --check

Churn note: one review-fix push after the draft candidate. I am marking this PR ready for review now.

[greptile-apps]

Greptile Summary

This PR reorganizes the package documentation boundary.

• Moves maintainer docs under internal/docs/.
• Moves agent workflow playbooks under internal/docs/agent-workflows/.
• Replaces docs/README.md with a short public boundary note.
• Updates README, agent, archive, and test references for the new paths.

Confidence Score: 5/5

This looks safe to merge after a small docs-navigation cleanup.

• No blocking issues found in the changed code.
• The only follow-up is preserving navigation from old per-topic docs paths.

docs/README.md

Important Files Changed

Filename	Overview
README.md	Reframes the repository README around internal-use documentation and updates maintainer policy links.
docs/README.md	Adds the public documentation boundary note, but old per-topic docs paths no longer have stubs.
internal/docs/README.md	Adds the internal maintainer docs index for the moved runbooks and workflow directory.
internal/docs/agent-workflows/README.md	Adds an index for the moved agent workflow documentation.
.agents/skills/README.md	Updates skill documentation links to the new agent workflow docs location.
.agents/workflows/pr-processing.md	Updates workflow references to the new agent workflow docs location.
AGENTS.md	Updates repository guidance for the new public and internal documentation layout.
CLAUDE.md	Updates release, versioning, and runtime documentation paths to internal/docs/.

_{Reviews (1): Last reviewed commit: "Clarify internal agent workflow docs hom..." | Re-trigger Greptile}

[claude]

Review: Organize package docs as internal

Reviewed the full diff (gh pr diff 178). This is a docs-only reorganization (file moves + relative-link fixups), and I traced every rename and every touched relative link.

Findings: none. Specifically verified:

• No stale references to the old paths (internal/contributor-info/, docs/internal/, or the individual moved docs/*.md files) remain anywhere in the repo outside this diff.
• Every relative link in the renamed/relocated files resolves to a real file at its new depth, including in files with no in-diff line changes (e.g. internal/docs/repo-improvement-audit-2026-06.md, internal/docs/rsc-webpack-plugin-known-problems.md) where the move didn't require a link update.
• docs/README.md and internal/docs/README.md/internal/docs/agent-workflows/README.md all point to files that actually exist at those paths.
• As a nice side effect, the move from docs/internal/ → internal/docs/css-to-component-association-approaches.md corrects two ../src/... links that were already broken pre-PR (wrong depth) into working ../../src/... links.

No code, build, or CI config changes are affected (no path filters reference the old doc locations). Nothing to flag — looks safe to merge from a correctness standpoint.

[claude]

Review: docs-only reorganization

Reviewed the diff (28 files changed, docs moved under internal/docs/ with a public docs/README.md boundary note).

Verification performed: rather than trust the PR's self-reported link check, I exhaustively re-extracted every relative markdown link (](path), excluding http(s):///mailto:/pure-anchor links) across all .md files in the repo and resolved each one against its source file's directory. Also grepped non-markdown files (workflows, scripts, source, tests) for stale docs/ references.

Result: no broken links or stale references found.

Specifically verified correct, since this is the failure mode this kind of reorg PR usually gets wrong:

• Files moved from internal/contributor-info/ (2 levels deep) to internal/docs/agent-workflows/ (3 levels deep) correctly bumped ../../ → ../../../ for root-relative links (e.g. AGENTS.md, .agents/workflows/pr-processing.md).
• docs/internal/*.md → internal/docs/*.md renames (same depth, 2 levels) correctly adjusted ../src/... → ../../src/... in css-to-component-association-approaches.md — this link was actually broken before the PR (pointed at nonexistent docs/src/...) and is now fixed as a side effect of the move.
• docs/*.md → internal/docs/*.md (depth 1 → 2) links updated consistently.
• New docs/README.md, internal/docs/README.md, and internal/docs/agent-workflows/README.md "Contents" indexes all match the actual files present in their directories — no missing or orphaned entries.
• AGENTS.md, CLAUDE.md, README.md, and skill front matter (rsc-triage, react-upgrade) are consistently updated to the new paths.
• No leftover files under old docs/internal/ or internal/contributor-info/ paths.

Nothing further stood out — no correctness bugs, security implications, or performance concerns apply to a docs-only move. LGTM.

[justin808]

Incremental review-fix evidence for latest push (512d5a4):

• Added lightweight pointer stubs at the old moved docs paths, including the former docs/internal/* paths, so older GitHub links reach the new internal/docs/* files instead of 404ing.
• Updated docs/README.md to state that former topic paths are retained as pointers only.

Local validation after this push:

• git diff --check
• yarn build
• yarn test (one earlier tests/rspack-compat/client-browser.rspack.test.ts worker SIGSEGV was transient; yarn test:non-rsc and the final full yarn test rerun passed).

[claude]

Review

This PR reorganizes package docs: maintainer-facing docs move from docs/ to internal/docs/, contributor playbooks move from internal/contributor-info/ to internal/docs/agent-workflows/, and the old docs/*.md paths become short "# Moved: ..." stubs pointing at the new location (so existing external links don't 404). docs/README.md stays as the small public-doc boundary note, and referrers (README.md, AGENTS.md, CLAUDE.md, .agents/skills/*, .agents/workflows/pr-processing.md, the archived patch READMEs, and one comment in tests/webpack-plugin/plugin-integration.test.ts) were all updated to the new paths.

I ran this through 4 independent review angles (line-by-line link/path verification, removed-content audit via blob-hash diffing, whole-repo cross-file reference tracing, and a reuse/simplification/altitude/conventions pass) — no findings survived verification. Specifically confirmed:

• Every stub in docs/*.md resolves to a real file in internal/docs/, with relative-path depth (../ vs ../../) correctly adjusted for the new nesting level.
• Content in the moved files is byte-identical (or differs only by intentional path-depth fixes) versus the old docs/*.md originals — nothing was dropped or truncated in transit.
• A repo-wide git grep for the old paths (docs/releasing.md, docs/versioning.md, docs/eliminate-react-fork.md, docs/open-rsc-work-status.md, internal/contributor-info/..., docs/internal/...) turns up zero stale references outside the intentional stub bodies.
• No CI workflow or script does markdown link-checking today, so the two parallel doc trees (docs/ stubs + internal/docs/ real content) don't create double-scanning overhead.
• The stub convention is new but not a reinvention of an existing pattern, and is consistently formatted across all 10 stub files.

Nice, clean mechanical move. Nothing to change.