dev-docs: introduce application_model.md as entry point, normalize naming, clean work/

[cboos]

Summary

Restructures dev-docs/ and work/ so the directories cleanly separate as-built reference (dev-docs/) from plans/TODOs (work/), and introduces a lean entry-point document for dev-docs/.

• New dev-docs/application_model.md — entry-point doc covering subsystems, data lifecycle, glossary, and inline coverage of subsystems without their own deep-dive (CLI, TUI, cache implementation, migrations, detail-level filter, image export, performance profiling).
• dev-docs/FOLD_STATE_DIAGRAM.md → dev-docs/message-hierarchy.md (drops the SCREAMING_SNAKE; H1 also updated).
• dev-docs/restoring-archived-sessions.md → docs/restoring-archived-sessions.md (user-facing operations; docs/ is the new home for end-user documentation).
• dev-docs/rendering-next.md → work/rendering-next.md (it was always future-work content).
• work/phase-c-agent-transcripts.md deleted: the work fully landed via Integrate agent transcripts into the DAG (Phase C) #99; the as-built reality is now in agents.md.
• Inbound references updated in CLAUDE.md, CONTRIBUTING.md, claude_code_log/converter.py (URL points at docs/), and the four dev-docs/*.md files that cross-referenced the moved/renamed pages.
• Surviving dev-docs all carry a one-line breadcrumb pointing at application_model.md so a reader landing on a deep-dive without context finds the system overview.

Validation

A second commit (027f8c6) folds in three follow-up fixes from a docs-walk-through with a fresh reader — they navigated application_model.md → dag.md → messages.md cleanly to investigate a hypothetical branch-heading rendering bug, but flagged that the label composition surface (_branch_label, _enrich_branch_titles, create_session_preview, simplify_command_tags) wasn't reachable from the docs alone:

1. New SessionHeaderMessage glossary entry naming the four functions involved.
2. Cross-reference in dag.md's "Navigation Links" section pointing at the glossary entry — keeps dag.md focused on structure without leaving a silent dead end on labeling.
3. Cross-cutting-concerns paragraph after the § 1 subsystem table calling out "label and preview composition" as the canonical multi-row concern.

Resulting structure

dev-docs/
├── application_model.md      ← entry point (new)
├── rendering-architecture.md (stays — pipeline deep-dive)
├── dag.md
├── messages.md + messages/
├── agents.md
├── teammates.md
├── message-hierarchy.md      ← renamed from FOLD_STATE_DIAGRAM.md
├── css-classes.md
└── implementing-a-tool-renderer.md

docs/                          ← new directory (user-facing)
└── restoring-archived-sessions.md

work/
├── async-agents.md
├── rendering-next.md         ← moved from dev-docs/
└── session-state-propagation.md

Test plan

• Doc-only changes; no code or tests affected.
• Inbound references checked: grep -rIn "FOLD_STATE_DIAGRAM\|phase-c-agent-transcripts" returns nothing outside test fixtures.
• Breadcrumb links in each surviving dev-docs/*.md resolve (relative paths verified).
• CLAUDE.md and CONTRIBUTING.md Architecture sections updated to point at application_model.md first.
• Cold-read navigation walk-through with a fresh reader: entry point worked end-to-end; gaps surfaced by the walk-through are addressed in the follow-up commit.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation

• Documentation
  • Reorganized documentation structure with improved navigation across user guides (docs/), development documentation (dev-docs/), and work plans (work/).
  • Added comprehensive system overview guide to streamline onboarding and provide clearer entry points for learning key subsystems, data flow, and architecture.
  • Updated documentation cross-references to improve consistency and navigation between related topics.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR restructures developer documentation by introducing a central application model reference document that serves as the entry point for the claude-code-log system. It updates cross-references throughout existing docs, reorganizes directory structure (docs/, work/, dev-docs/), deletes an obsolete work-in-progress document, and corrects internal link paths. One user-facing message string is updated to reference the new docs/ location.

Changes

Cohort / File(s)	Summary
Primary Navigation Hub dev-docs/application_model.md	New comprehensive system overview documenting subsystems, cache lifecycle, migrations, data flow, glossary terms, and "where to start" guidance for contributors (361 lines).
Navigation Updates across Dev Docs dev-docs/agents.md, dev-docs/css-classes.md, dev-docs/implementing-a-tool-renderer.md, dev-docs/teammates.md	Each adds a cross-reference pointer to application_model.md for system context.
Core Architecture Docs with Enhanced Links dev-docs/dag.md, dev-docs/message-hierarchy.md, dev-docs/messages.md, dev-docs/rendering-architecture.md	Add references to application_model.md and/or update cross-references (e.g., FOLD_STATE_DIAGRAM.md renamed to message-hierarchy.md, future doc paths adjusted to ../work/ prefix).
Repository Navigation Docs CLAUDE.md, CONTRIBUTING.md	Restructure documentation navigation: introduce application_model.md as primary reference, describe docs/, work/, and dev-docs/ directory purposes and starting points.
User-Facing Documentation Update claude_code_log/converter.py	Update archived-sessions note URL from dev-docs/ to docs/ directory.
Work-in-Progress Cleanup & Path Updates work/phase-c-agent-transcripts.md (deleted), work/rendering-next.md	Remove obsolete Phase C agent transcript design doc; update rendering-next.md relative links to point to ../dev-docs/ files.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Possibly related PRs

• PR #86: Updates repository documentation structure and CONTRIBUTING.md alongside similar doc hierarchy and reference improvements.

Suggested reviewers

• daaain

Poem

🐇 A map emerges from the doc-filled wood,
Where scattered notes now gather as they should.
One central guide illuminates the way,
Through subsystems and flows, both night and day.
The work is neat, the paths are clear—
Welcome, explorer, start right here! 📚✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main changes: introducing application_model.md as an entry point, normalizing naming conventions, and cleaning up the work/ directory.
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

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev/dev-docs-restructure

---

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

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

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

[coderabbitai]

🧹 Nitpick comments (1)

dev-docs/application_model.md (1)

361-361: Optional: Simplify redundant phrase.

The phrase "in-flight or proposed plan" could be shortened to just "plan" since "in-flight" and "proposed" both already imply it's a plan.

✨ Suggested simplification

-  → [`work/`](../work/) — each `.md` is an in-flight or proposed plan.
+  → [`work/`](../work/) — each `.md` is a plan (in-flight or proposed).

or simply:

-  → [`work/`](../work/) — each `.md` is an in-flight or proposed plan.
+  → [`work/`](../work/) — each `.md` documents planned work.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@dev-docs/application_model.md` at line 361, Replace the redundant phrase in
the documentation entry "→ [`work/`](../work/) — each `.md` is an in-flight or
proposed plan." by changing "in-flight or proposed plan" to simply "plan" so the
line reads "→ [`work/`](../work/) — each `.md` is a plan."; update the
corresponding text in dev-docs/application_model.md where that exact phrase
appears.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@dev-docs/application_model.md`:
- Line 361: Replace the redundant phrase in the documentation entry "→
[`work/`](../work/) — each `.md` is an in-flight or proposed plan." by changing
"in-flight or proposed plan" to simply "plan" so the line reads "→
[`work/`](../work/) — each `.md` is a plan."; update the corresponding text in
dev-docs/application_model.md where that exact phrase appears.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bb304ab2-92ee-4115-9c32-5cb7c1daf4ae

📥 Commits

Reviewing files that changed from the base of the PR and between 294ed3b and 027f8c6.

📒 Files selected for processing (15)

• CLAUDE.md
• CONTRIBUTING.md
• claude_code_log/converter.py
• dev-docs/agents.md
• dev-docs/application_model.md
• dev-docs/css-classes.md
• dev-docs/dag.md
• dev-docs/implementing-a-tool-renderer.md
• dev-docs/message-hierarchy.md
• dev-docs/messages.md
• dev-docs/rendering-architecture.md
• dev-docs/teammates.md
• docs/restoring-archived-sessions.md
• work/phase-c-agent-transcripts.md
• work/rendering-next.md

💤 Files with no reviewable changes (1)

• work/phase-c-agent-transcripts.md