# Per-directory README + AGENTS.md (https://jackin.tailrocks.com/roadmap/per-directory-readme/)



**Status**: Partially implemented — workspace-wide Rust rules and several crate-level orientation files are already current; five crates in `crates/` still have no <RepoFile path="README.md">README.md</RepoFile> or <RepoFile path="AGENTS.md">AGENTS.md</RepoFile>

## Shipped facts [#shipped-facts]

<RepoFile path="crates/AGENTS.md">crates/AGENTS.md</RepoFile> already documents the workspace-wide Rust rules for the current crate layout: Rust 2024 self-named module files (no `mod.rs`), the `tests.rs` convention, naming, and the lint/supply-chain baseline. No stale pre-split `src/` language remains there. Seven of the nineteen `crates/*` directories have their own orientation file: <RepoFile path="crates/jackin-capsule/README.md">jackin-capsule</RepoFile>, <RepoFile path="crates/jackin-build-meta/README.md">jackin-build-meta</RepoFile>, <RepoFile path="crates/jackin-pr-trailers/README.md">jackin-pr-trailers</RepoFile>, <RepoFile path="crates/jackin-protocol/README.md">jackin-protocol</RepoFile>, <RepoFile path="crates/jackin-term/README.md">jackin-term</RepoFile>, and <RepoFile path="crates/jackin-tui/README.md">jackin-tui</RepoFile> each carry a <RepoFile path="README.md">README.md</RepoFile>, and <RepoFile path="crates/jackin-tui-lookbook/AGENTS.md">jackin-tui-lookbook</RepoFile> carries an <RepoFile path="AGENTS.md">AGENTS.md</RepoFile>. <RepoFile path="docs/AGENTS.md">docs/AGENTS.md</RepoFile> is also current for the Fumadocs site layout.

## Target directories still missing an orientation file [#target-directories-still-missing-an-orientation-file]

| Directory                | README or AGENTS.md should say                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `crates/jackin/`         | CLI binary crate: command dispatch, app context, command handlers, and root integration tests.                            |
| `crates/jackin-runtime/` | Container bootstrap pipeline, instance lifecycle, launch pipeline, DinD sidecar management, isolation, and runtime tests. |
| `crates/jackin-console/` | Operator console TUI state, input/update, screens, services, and shared console components.                               |
| `crates/jackin-config/`  | Config loading, persistence, editing, schema versions, and migrations.                                                    |
| `crates/jackin-env/`     | Operator environment resolution, 1Password references, picker metadata, and launch diagnostics.                           |

## Rules for crate guidance [#rules-for-crate-guidance]

* Keep each orientation file short: entrypoints and invariants, not a second codebase map.
* Do not create or recommend `mod.rs`; crates use Rust 2024 self-named module files such as `foo.rs` plus `foo/tests.rs`.
* Point durable source navigation to [Codebase Map](/reference/getting-oriented/codebase-map/) and root <RepoFile path="PROJECT_STRUCTURE.md">PROJECT\_STRUCTURE.md</RepoFile>.

## Remaining work [#remaining-work]

1. Add a crate-level <RepoFile path="README.md">README.md</RepoFile> or <RepoFile path="AGENTS.md">AGENTS.md</RepoFile> for the five crates listed above, each covering entrypoints and invariants only.
2. Keep the docs-site and repo-root source maps aligned when a crate boundary changes.