Docs IA reorg + mdBook setup + changelog migration

[robertguss]

Objective

Create a maintainable documentation information architecture, add mdBook navigation/build support, and preserve historical context in a single changelog so legacy planning files can be retired.

Risk Tier

• Tier: 1
• Rationale: Repository-level docs/process/tooling changes with low runtime risk but high contributor workflow impact.

Scope

• In scope: docs/ reorganization, link updates, mdBook scaffolding (book.toml, docs/SUMMARY.md), changelog creation, retirement of two legacy root markdown files, and docs-only path classification update in scripts/validate_tdd_cycle.sh.
• Out of scope: Contract policy semantics, CLI runtime behavior, release artifact format, and CI job topology.

Red

• Failing test(s): Documentation IA and historical-record workflow were fragmented (flat docs layout plus separate legacy planning docs pending retirement).
• Command(s): rg -n "09-upstream-tiger-style-v1\.1-patch-list\.md|CONTRACT_SYSTEM_V2\.md"
• Failure summary: Historical updates were split across separate source files and docs discoverability was degraded by a flat structure with growing link maintenance overhead.
• Expected failure rationale: Without a unified changelog and structured docs layout, contributor onboarding and long-term maintenance drift increase.

Green

• Command(s): scripts/validate_tdd_cycle.sh --base origin/main --allow-empty-range; bash -n scripts/validate_tdd_cycle.sh; just book-build
• Passing summary: TDD sequence validator passed for origin/main..HEAD, script syntax check passed, and mdBook build succeeded.

Refactor

• Why behavior is unchanged: Changes are documentation/process oriented; no production runtime logic or CLI command semantics were altered.
• Confirmation commands: just book-build; scripts/validate_tdd_cycle.sh --base origin/main --allow-empty-range

Invariants

• Core contract enforcement remains active.
• PR evidence schema and TDD commit taxonomy remain enforced.
• Active language contract manifest behavior is unchanged.

Security Impact

No new permissions, secrets handling, network paths, or trust-boundary behavior introduced.

Performance Impact

No runtime performance impact; only docs build/navigation structure changed.

Assumptions

• mdBook remains the preferred docs renderer for this repository.
• Retired legacy files are fully represented by CHANGELOG.md entries.

Open Questions

• Should we add a lightweight markdown-link checker in CI to prevent future link drift after docs moves?

Rollback Plan

• Revert this PR to restore the previous flat docs layout and undelete the two retired root files.
• If needed, keep CHANGELOG.md but back out docs path migration independently.

Validation Commands

• scripts/validate_tdd_cycle.sh --base origin/main --allow-empty-range
• bash -n scripts/validate_tdd_cycle.sh
• just book-build

Summary by CodeRabbit

• New Features

  • Added mdBook support for local documentation rendering with build and serve commands.

• Documentation

  • Reorganized documentation structure with new directory layout (getting-started, guides, tooling, reference, decisions, templates).
  • Added comprehensive CHANGELOG documenting repository-level updates.
  • Updated internal documentation links to reflect new structure.
  • Added new CLI installation option from repository.

• Chores

  • Removed legacy documentation files.
  • Updated build tooling configuration.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation repository reorganized to use mdBook for site generation, with removal of two legacy documentation files (upstream patch list and Contract System v2) and introduction of structured documentation directories. Configuration added for mdBook with build recipes. Multiple documentation links updated to reflect new directory hierarchy.

Changes

Cohort / File(s)	Summary
mdBook Configuration & Setup book.toml, .gitignore, justfile	Added mdBook configuration file, docs/book/ ignore rule, and three new recipes (book-build, book-serve, book-install) for documentation generation and local serving.
Documentation Removed 09-upstream-tiger-style-v1.1-patch-list.md, CONTRACT_SYSTEM_V2.md	Deleted upstream Tiger Style v1.1 patch list draft (409 lines) and Contract System v2 documentation (35 lines); no functional code impact.
Documentation Indexes & Changelog CHANGELOG.md, docs/SUMMARY.md	Added CHANGELOG.md tracking repository changes across two dates with Added/Changed items and retired documents section; added SUMMARY.md as mdBook navigation index organizing documentation across overview, getting-started, guides, tooling, reference, decisions, and templates sections.
Root Documentation Updates README.md, docs/README.md	Updated README.md with structured doc links under new directories, added mdBook local render commands and CLI development setup; updated docs/README.md to document new subdirectory structure and provide updated navigation to files organized under getting-started, guides, tooling, reference, decisions, and templates.
Documentation Path Reorganization docs/getting-started/adopting-in-a-new-project.md, docs/getting-started/quickstart.md, docs/guides/agents-integration.md, docs/guides/ci-and-validation.md, docs/reference/faq.md, docs/reference/glossary.md, docs/reference/language-contracts.md, docs/reference/risk-tiers-and-controls.md, docs/tooling/cli.md	Unified link path updates across all documentation files from flat or relative paths to new directory-aware relative paths reflecting reorganized structure; added local installation instruction for Tiger Style CLI via just/cargo in tooling docs.
Validation Script Update scripts/validate_tdd_cycle.sh	Replaced CONTRACT_SYSTEM_V2.md with CHANGELOG.md in non-executable documentation path validation logic.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Contract System v2: core contracts, enforcement, and CI gates #1: Adds CONTRACT_SYSTEM_V2.md and Contract System v2 documentation alongside mdBook setup—directly inverse to this PR's removal of the same contract documentation file.

Poem

🐰 Hoppy times in docs today,
Directories reorganized—hurray!
mdBook arrives with SUMMARY's light,
Links rewired, structure set right,
Legacy contracts tucked away in history's sight! 📚

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: docs IA reorganization, mdBook setup, and changelog migration are all present and significant in the changeset.
Description check	✅ Passed	The PR description follows the template structure with all major sections completed: Objective, Risk Tier, Scope, Red/Green/Refactor evidence, Invariants, Security/Performance Impact, Assumptions, Open Questions, Rollback Plan, and Validation Commands.

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/docs-mdbook-changelog-reorg

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@docs/README.md`:
- Around line 7-8: Replace the machine-specific absolute path
'/Users/robertguss/Projects/programming_tiger_style/book.toml' in the README
text with a repo-relative path (e.g., 'book.toml' or './book.toml') so other
contributors aren’t misled; update the sentence "This folder is the mdBook
source (`/Users/robertguss/Projects/programming_tiger_style/book.toml`)." to
reference the relative path and keep the rest of the instructions (Run `just
book-serve` ...) unchanged.

🧹 Nitpick comments (1)

justfile (1)

76-86: LGTM!

The mdBook recipes are clean and follow the existing justfile patterns. They integrate well with the new book.toml configuration.

Consider adding a comment noting that book-install should be run first if mdbook is not already installed, or optionally make it a soft dependency:

# Build mdBook docs to docs/book (run book-install first if mdbook is missing).
book-build:
  mdbook build

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Avoid machine-specific absolute path in docs.

/Users/robertguss/.../book.toml is local-only and will mislead other contributors. Use a repo-relative path instead.

✅ Suggested fix

-This folder is the mdBook source (`/Users/robertguss/Projects/programming_tiger_style/book.toml`).
+This folder is the mdBook source (`book.toml` at the repository root).

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	This folder is the mdBook source (`/Users/robertguss/Projects/programming_tiger_style/book.toml`).
	Run `just book-serve` from the repository root for a local docs site.
	This folder is the mdBook source (`book.toml` at the repository root).
	Run `just book-serve` from the repository root for a local docs site.

🤖 Prompt for AI Agents

In `@docs/README.md` around lines 7 - 8, Replace the machine-specific absolute
path '/Users/robertguss/Projects/programming_tiger_style/book.toml' in the
README text with a repo-relative path (e.g., 'book.toml' or './book.toml') so
other contributors aren’t misled; update the sentence "This folder is the mdBook
source (`/Users/robertguss/Projects/programming_tiger_style/book.toml`)." to
reference the relative path and keep the rest of the instructions (Run `just
book-serve` ...) unchanged.