docs(agents): document project structure and fix stale plan index

[bougyman]

Summary

• Adds a ## Project Structure section to AGENTS.md with: repository layout (two-project architecture and directory roles), layered module architecture (ASCII hierarchy), data-flow description, and a maintenance convention
• Fixes the stale Plan index — adds phase 9 (profiles), phase 10 (favorites), and phase 11 (bare issue numbers), which existed in documents/ but were missing from the index

Closes CRY-55.

Test plan

• mix compile — clean
• mix test — 12/12 pass
• <!-- usage-rules-start/end --> markers intact; mix usage_rules.sync is a no-op on the injected block
• Preamble section order: The Plan → Project Structure → Standards → usage-rules injection

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[bougyman]

Code Review

Issue: CRY-55 — Document and maintain the project structure
Branch: CRY-55-document-project-structure
Commit: 736c21a — docs(agents): document project structure and fix stale plan index
Reviewer: Independent code review (automated)

---

Summary

Single commit modifying only AGENTS.md (which CLAUDE.md symlinks to). Two changes:

1. Plan index fix — Added missing Phase 9, 10, 11 references. All three .adoc files confirmed to exist in documents/.
2. New "Project Structure" section — Documents the two-Mix-project layout, directory roles, layered module architecture (ASCII tree), data-flow description, and a maintenance convention.

Verification

• Compile (root): Clean, no warnings
• Compile (app): Clean, no warnings
• Tests (root): 12/12 pass
• Tests (app): 240/254 pass — 14 failures are pre-existing environment issues (SQLite disk I/O errors and git lock conflicts from the orchestrator worktree). No code changes on this branch; only AGENTS.md was modified.
• Format: Clean
• Section ordering: Project Structure is placed between "The Plan" and "Standards", before the <!-- usage-rules-start --> marker — sync workflow is unaffected.

Findings

Minor (1):

1. LinearCli.Api indentation is misleading (AGENTS.md line 64-65): In the ASCII module tree, LinearCli.Api is indented under LinearCli.Linear, visually suggesting it's a sub-module (like Linear.Issue, Linear.Team, etc.). In reality, LinearCli.Api is a peer at the LinearCli namespace level — it lives at app/lib/linear_cli/api.ex, not under app/lib/linear_cli/linear/. The Linear domain resources call LinearCli.Api, but it's not namespaced under LinearCli.Linear. Suggested fix: either outdent LinearCli.Api to the same level as LinearCli.Linear in the tree, or add a brief note that the indentation represents "called by" rather than namespace nesting.

Omissions (non-blocking, 2):

2. .github/ directory not mentioned — Contains workflows/ci.yaml, workflows/main.yaml, and workflows/usage-rules-sync.yaml. These are arguably important for contributors to know about. Could be listed among the supporting directories.

3. test/ (root) directory not mentioned — Contains tests for the root RepoTasks project (test/mix/tasks/). Minor since app/test/ is implicitly understood, but the root project's tests are less obvious.

What looks good

• The two-project architecture explanation is clear and would save a newcomer real confusion.
• Directory descriptions are accurate — every claim I verified matched the filesystem (bin scripts all call exec lc, vendor submodules match the listed names, schema/oci/cinemas contents match).
• Writing at the directory/layer level rather than file-by-file is the right call for maintainability.
• The maintenance convention at the end sets clear expectations for when to update the docs.
• Data-flow description and daemon-mode explanation are concise and correct.

Overall Assessment

Approve with minor suggestion. The LinearCli.Api indentation issue (finding #1) is a small accuracy improvement that could be addressed now or in a follow-up. The missing directories (#2, #3) are non-blocking and could be added if the maintainer agrees they're worth the extra lines. The core documentation is accurate, well-structured, and addresses the ticket's intent.