docs: split CLAUDE.md into per-directory guides

[kixelated]

Summary

Splits the monolithic root CLAUDE.md into per-directory guides that load automatically when an agent works under each language directory. The root file now holds only cross-cutting rules; language-specific detail (and a richer module map than the root previously had) lives next to the code it describes.

Why nested files, not @imports or skills: nested CLAUDE.md is the only mechanism that loads conditionally by location, so a Rust-only session no longer carries JS reactivity rules and vice versa. @import would load eagerly (no savings); skills are for actions (a pre-PR self-review skill is a sensible follow-up, but that is a separate concern from this reference knowledge).

New nested guides

• rs/CLAUDE.md - Cargo workspace: crate map (including kio, moq-json, moq-loc, moq-msf, moq-video that the root tree omitted), Producer/Consumer model, poll_* plumbing, error handling, config/TOML merge, Version matching, binary setup, testing.
• js/CLAUDE.md - bun workspace: package map (including @moq/json, @moq/loc, @moq/msf that the root tree omitted), the signals + Effect reactivity model and its lifecycle/cleanup rules, the Web Components UI pattern, bun/Biome tooling.
• py/CLAUDE.md - the moq-ffi (generated bindings) vs moq-rs (ergonomic wrapper) split and the moq public surface. Kept deliberately light per the wrappers-are-thin steer.

Root CLAUDE.md changes

• New Per-Directory Guides section pointing at each nested file.
• Removed Version Matching Convention and Rust Conventions (folded into rs/CLAUDE.md).
• Trimmed the four JS-specific Tooling bullets (TypeScript/bun, Biome, UI, JS async patterns; folded into js/CLAUDE.md); kept the cross-cutting ones (just, Nix, Local-first, CI).
• swift/, kt/, go/ are thin wrappers mirrored to external repos, so they defer to their existing README.mds rather than getting a dedicated guide.

No behavioral or public-API changes; documentation only. AGENTS.md is a symlink to CLAUDE.md, so it reflects the root automatically.

Public API changes

None.

Test plan

• Root file re-reads coherently; the moved sections are gone and the new pointer section resolves (#per-directory-guides anchor exists).
• No em dashes introduced (the only — is the literal one inside the "no em dashes" rule).
• Reviewer sanity-check that the nested crate/package maps match the current workspaces.

Follow-up (not in this PR)

A pre-submit self-review skill that leans on the Cross-Package Sync table and public-API/breaking-change rules. Better as a skill (invoked per action) than a memory file, and worth reviewing on its own.

(Written by Claude)

🤖 Generated with Claude Code

---

Generated by Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ac0800bc-6564-4f85-b4c5-d9b83dcf454b

📥 Commits

Reviewing files that changed from the base of the PR and between ab28431 and 57dd60e.

📒 Files selected for processing (3)

• rs/moq-bench/src/config.rs
• rs/moq-relay/src/config.rs
• rs/moq-relay/src/stats.rs

✅ Files skipped from review due to trivial changes (3)

• rs/moq-bench/src/config.rs
• rs/moq-relay/src/stats.rs
• rs/moq-relay/src/config.rs

---

Walkthrough

The root CLAUDE.md is restructured: a new Per-Directory Guides section is added that points agents to rs/CLAUDE.md, js/CLAUDE.md, py/CLAUDE.md, and README.md files for swift/kt/go wrappers. The Writing Style section is trimmed to only the no-em-dash rule, removing Rust conventions and version-matching guidance. The Tooling section replaces language-specific bullets with a pointer to the per-directory guides. Concurrently, three new guide files are created: rs/CLAUDE.md covers the Rust workspace crate map, Producer/Consumer model, async/poll conventions, and coding rules; js/CLAUDE.md covers the Bun workspace, Signals/Effect reactivity model, web component conventions, and ESM rules; py/CLAUDE.md covers the moq-ffi/moq-rs wheel split, module layout, and async/docstring conventions. Inline documentation comments in three Rust source files are updated to reference the new rs/CLAUDE.md location.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: splitting CLAUDE.md into per-directory guides, which matches the core objective of the PR.
Description check	✅ Passed	The description is directly related to the changeset, explaining the motivation, structure, and scope of splitting the root CLAUDE.md into language-specific nested guides with comprehensive detail.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/claude-md-organization-prpk6u

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@rs/CLAUDE.md`:
- Around line 72-79: The docstring comment containing "see `CLAUDE.md`" in
relation to TOML/CLI merge guidance needs to be updated after the documentation
reorganization. Find the comment that references CLAUDE.md for TOML merge/CLI
interaction rules and update it to reference rs/CLAUDE.md instead, ensuring the
external documentation link points to the correct location of the configuration
conventions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b7b598ac-a70e-40a6-b94c-ead8fbf097bf

📥 Commits

Reviewing files that changed from the base of the PR and between dbb41d8 and ab28431.

📒 Files selected for processing (4)

• CLAUDE.md
• js/CLAUDE.md
• py/CLAUDE.md
• rs/CLAUDE.md