Lead /project-documentation output with behavior, demote technical reference

[mxriverlynn]

Summary

This PR restructures the `project-documentation` skill's output template so generated feature docs lead with plain-language behavior and demote code reference, so that a reader can understand what a feature does before wading into its implementation.

• Generated feature docs now open with a behavioral spine: a prose Summary, an Architecture diagram, a How It Works overview, and Primary Flows that narrate the main paths step by step. All schema, type, constant, and implementation detail is collected below a new `## Technical Reference` region.
• A reader who only needs to know what a feature does can stop after Primary Flows and never read the Technical Reference. The reference layer becomes lookup material (file-and-function pointers with short snippets) rather than reproduced 10-30 line source blocks.
• Diagrams switch from ASCII box-drawing and tree art to Mermaid (`flowchart` for structure and trees, `sequenceDiagram` for actor-to-system exchanges), so they render as real diagrams on GitHub and in doc viewers.
• This changes the shape of every doc the skill produces going forward; it does not touch the skill's eight-step process flow or its agent dispatch. Existing docs are not rewritten by this PR, but update mode now adds the behavioral layer when an older doc lacks one.

Behavior changes

The skill itself is a process that produces a document, so the runtime change is in what the skill writes, not in how Claude Code runs it.

• Before: generated docs led with `## Overview`, then reference sections (Database Schema, Core Types with full type definitions, Implementation Details with 10-30 line annotated code blocks), with ASCII diagrams.
• After: generated docs lead with `## Summary` (prose paragraph plus bullets plus a Key files quick list), `## Architecture` (Mermaid), `## How It Works`, and `## Primary Flows`. Configuration and Error Handling move up to sit with the behavioral content. Everything else moves below a `## Technical Reference` horizontal-rule region as H3 sub-sections (Data Model, Core Types, Constants, Implementation Notes, API Endpoints, Events, Frontend Components, Adding a New Item, Testing, Troubleshooting).
• Update mode change: when updating a doc that has no plain-language behavioral layer, the skill now adds Summary, How It Works, and Primary Flows at the top rather than only editing existing sections.
• The Step 7 information-architect review changes its target audience from "a developer who needs to understand or change this feature" to "a developer or technically-literate stakeholder who needs to understand the feature's behavior before reading its code," and now treats "behavior leads, code reference follows" as a pass/fail gate rather than returning an empty list when prose reads well.

What to look at first

• The reorientation decision in `SKILL.md`: writing rules now lead with four "lead with behavior" rules (Summary as prose plus bullets, Primary Flows narrate main paths, reference is supporting detail) before the cross-cutting rules. This is the core behavioral contract for what the skill produces.
• The "pointers over long code" tradeoff: Technical Reference now points to file and function and shows a short snippet only where the source is non-obvious, instead of reproducing 10-30 line blocks. Worth a look at whether that loses useful detail for the reference-seeking reader.
• The Step 7 IA-review prompt change, which converts the audit into an explicit five-point check with a behavior-leads gate, so a doc that buries behavior below reference now fails the review.
• The DITA mapping note in the long-form doc: Summary and How It Works are "concept," Primary Flows are "task," and the Technical Reference region is "reference," which is the rationale for the new ordering.

Files of interest

• `han.core/...documentation/references/template.md` — the restructured output template; the heart of the change (Overview to Summary, new How It Works and Primary Flows, Technical Reference region, Mermaid diagrams).
• `han.core/skills/project-documentation/SKILL.md` — the writing rules, update-mode behavior, Step 7 IA prompt, and Step 8 verification that enforce the new structure.
• `docs/skills/project-documentation.md` — operator-facing long-form doc updated to describe the behavior-first output and the DITA rationale.