feat: add evidence-led README directions

.github/workflows/ci.yml

@@ -17,5 +17,5 @@ jobs:
         with:
           python-version: "3.12"
       - run: python -m unittest discover -s tests -v
-      - run: python skills/beautify-readme/scripts/validate_skill.py
-      - run: python skills/beautify-readme/scripts/check_readme.py .
+      - run: python skills/refine-readme/scripts/validate_skill.py
+      - run: python skills/refine-readme/scripts/check_readme.py .

README.md

@@ -5,7 +5,8 @@
 <p align="center">
   <a href="skills/refine-readme/SKILL.md">Agent Skill</a> ·
   <a href="#quick-start">Quick start</a> ·
-  <a href="#six-project-native-cover-directions">Cover styles</a> ·
+  <a href="#from-repository-evidence-to-three-directions">Directions</a> ·
+  <a href="#real-before--after">Before / After</a> ·
   <a href="#what-it-delivers">What it delivers</a>
 </p>
 
@@ -51,21 +52,35 @@ Or run the deterministic helpers directly:
 
 ```bash
 python skills/refine-readme/scripts/inspect_repository.py /path/to/repository
+python skills/refine-readme/scripts/plan_directions.py /path/to/repository
 python skills/refine-readme/scripts/check_readme.py /path/to/repository
 python skills/refine-readme/scripts/render_cover.py \
   --style protocol-grid \
   --title "My Project" \
   --tagline "One clear promise backed by real proof" \
+  --eyebrow "ASYNC VIDEO API" \
+  --proof-label "POST /v1/tasks" \
   --output assets/readme/cover.svg
 ```
 
-## Six project-native cover directions
+## From repository evidence to three directions
+
+Before creating a cover, the Skill resolves five things: audience, one-sentence
+value, primary proof, first successful action, and native visual material. It
+then proposes three directions that each identify a repository-specific motif,
+proof source, construction mode, hero composition, and risk.
+
+The bundled styles below are direction seeds, not fixed templates. Their palette,
+composition, and proof slots are adapted to the project. If removing the project
+name would make the result fit an unrelated repository, the direction fails.
+
+## Six cover direction seeds
 
 <p align="center">
   <img src="assets/readme/style-wall.svg" alt="Six README Refiner cover directions: Protocol Grid, Product Proof, Research Field, Ink Archive, Modular Build, and Integration Bridge" width="100%" />
 </p>
 
-| Style | Best for | Visual language |
+| Seed | Best for | Visual language |
 | --- | --- | --- |
 | Protocol Grid | APIs, SDKs, CLIs, infrastructure | Terminal rhythm, request/response blocks, grids, system paths |
 | Product Proof | SaaS, web apps, AI tools | Real screenshots or outputs framed by precise SVG typography |
@@ -77,14 +92,33 @@ python skills/refine-readme/scripts/render_cover.py \
 Generated imagery never owns exact project text. When a style needs an organic
 subject, image generation creates only the subject or background; deterministic
 SVG overlays the project name, commands, labels, and factual claims.
+User covers contain no README Refiner watermark or branding by default.
+
+## Real Before / After
+
+<p align="center">
+  <img src="assets/readme/awesome-3d-prompts-before-after.svg" alt="Awesome 3D Prompts README before and after: a text-only 29-case table becomes a visual 300-plus-case gallery with a hero, workflow navigation, result media, and evidence labels" width="100%" />
+</p>
+
+The public [`BeatAPI/awesome-3d-prompts`](https://github.com/BeatAPI/awesome-3d-prompts)
+history provides a durable comparison: the
+[`a591c0f` snapshot](https://github.com/BeatAPI/awesome-3d-prompts/blob/a591c0ffee88fb5d529f4da0931465ce37980a25/README.md)
+is an 80-line, text-first catalog with 29 accepted cases; the
+[`ac37217` snapshot](https://github.com/BeatAPI/awesome-3d-prompts/blob/ac37217b7b723fbe38095503e06e3b818fbb1a85/README.md)
+is a 300+ case visual gallery with a hero, workflow navigation, result media,
+prompt-fidelity labels, and source attribution.
+
+[See the evidence and exact comparison](examples/awesome-3d-prompts-before-after.md).
+This is a real repository-history reference for the Refiner quality bar, not a
+claim that this Skill authored the historical commits.
 
 ## Modes
 
 | Mode | Behavior |
 | --- | --- |
 | `audit` | Read-only review of clarity, proof, trust, and maintenance cost |
 | `cover` | Recommend three directions and create cover assets only |
-| `beautify` | Apply the complete five-layer workflow and produce a README diff |
+| `beautify` | Apply the complete project-native workflow and produce a README diff |
 | `check` | Run factual and GitHub rendering checks without redesigning |
 
 No mode commits, pushes, opens a pull request, or publishes without explicit
@@ -116,8 +150,9 @@ assets/readme/architecture.svg    optional workflow or system explanation
 
 ## Status
 
-This is the first public version. The core workflow, six cover presets, repository
-inspector, README checker, and deterministic SVG renderer are available now.
+This is the first public version. The project-native direction gate, six cover
+seeds, repository inspector, direction planner, README checker, and deterministic
+SVG renderer are available now.
 GitHub-like browser previews, additional project fixtures, and continuous README
 checks will be added through real repository usage.
 

examples/awesome-3d-prompts-before-after.md

@@ -0,0 +1,53 @@
+# Awesome 3D Prompts: real README before and after
+
+This comparison uses two immutable commits from the public
+[`BeatAPI/awesome-3d-prompts`](https://github.com/BeatAPI/awesome-3d-prompts)
+repository. It is a reference for README Refiner's quality bar, not a claim that
+README Refiner authored the historical change.
+
+## Fixed snapshots
+
+- **Before:** [`a591c0ffee88fb5d529f4da0931465ce37980a25`](https://github.com/BeatAPI/awesome-3d-prompts/blob/a591c0ffee88fb5d529f4da0931465ce37980a25/README.md)
+- **After:** [`ac37217b7b723fbe38095503e06e3b818fbb1a85`](https://github.com/BeatAPI/awesome-3d-prompts/blob/ac37217b7b723fbe38095503e06e3b818fbb1a85/README.md)
+- **README diff:** [`a591c0f...ac37217`](https://github.com/BeatAPI/awesome-3d-prompts/compare/a591c0ffee88fb5d529f4da0931465ce37980a25...ac37217b7b723fbe38095503e06e3b818fbb1a85)
+
+## Evidence ledger
+
+| Signal | Before | After |
+| --- | --- | --- |
+| README length | 80 lines | 949 lines |
+| Catalog size | 29 accepted cases | 306 source-backed cases |
+| Opening visual | None | Repository-owned hero image |
+| Result proof | Text tables link to detail pages | Featured entries show visible result media in the README |
+| Navigation | Category headings | Six workflow links with counts |
+| Trust cues | Source and rights explanation | Source attribution, prompt-fidelity labels, evidence notes, and rights links |
+| Media summary | No media summary | 250 WebM videos and 56 WebP images |
+
+Counts above are read from the two committed READMEs and their committed prompt
+data. The comparison does not change or reinterpret the source prompts.
+
+## What changed in the reading experience
+
+The earlier README is accurate, but a visitor must read tables and open detail
+pages before seeing why the collection is useful. The later README leads with a
+clear promise, visible output, workflow-level navigation, and evidence labels.
+The underlying source discipline remains intact; the presentation makes that
+discipline easier to understand and trust.
+
+This is the pattern README Refiner should reproduce on other repositories:
+
+1. preserve repository truth;
+2. move the strongest real proof forward;
+3. establish a project-native visual system;
+4. improve scanning without hiding detail;
+5. keep every important claim traceable to source.
+
+## Reproduce the comparison
+
+From a clone of the 3D prompt repository:
+
+```bash
+git show a591c0ffee88fb5d529f4da0931465ce37980a25:README.md
+git show ac37217b7b723fbe38095503e06e3b818fbb1a85:README.md
+git diff a591c0ffee88fb5d529f4da0931465ce37980a25..ac37217b7b723fbe38095503e06e3b818fbb1a85 -- README.md
+```

skills/refine-readme/SKILL.md

@@ -16,14 +16,14 @@ wants `audit`, `cover`, `beautify`, or `check`.
 
 - `audit`: inspect and report only; do not edit files.
 - `cover`: create visual assets only; do not edit README content or references.
-- `beautify`: execute the complete five-layer workflow and propose a README diff.
+- `beautify`: execute the complete project-native workflow and propose a README diff.
 - `check`: validate facts and GitHub rendering without redesigning.
 
 Reading repository files does not grant permission to edit, commit, push, open a
 pull request, or publish. Always preview first. Require separate explicit
 approval for commit, push, PR, and publication actions.
 
-## Run the five-layer workflow
+## Run the project-native workflow
 
 1. Establish repository truth.
    - Inspect the current README, manifests, package scripts, public routes,
@@ -33,7 +33,19 @@ approval for commit, push, PR, and publication actions.
    - Build a fact ledger that separates confirmed evidence, reasonable
      inference, user-supplied claims, and unsupported claims.
 
-2. Rebuild the story and Markdown hierarchy.
+2. Pass the project-native direction gate.
+   - Resolve the audience, one-sentence value, primary proof, first successful
+     action, and native visual material before selecting a style.
+   - Run `scripts/plan_directions.py <repository>` for three evidence-led
+     candidates, then sharpen them with repository-specific reasoning.
+   - If the planner reports a blocked gate, request repository evidence instead
+     of returning arbitrary zero-evidence styles.
+   - For every direction, explain why it fits, its project-native motif, its
+     real proof, construction mode, hero composition, and primary risk.
+   - Treat bundled styles as seeds and constraints, not immutable templates.
+   - Read `references/project-native-directions.md` before recommending styles.
+
+3. Rebuild the story and Markdown hierarchy.
    - Make the first screen answer what the project is, who it is for, what proof
      exists, and how to try it.
    - Move real screenshots, outputs, examples, or a minimal command ahead of
@@ -42,28 +54,29 @@ approval for commit, push, PR, and publication actions.
      precise and scannable.
    - Read `references/five-layer-workflow.md` for the default section logic.
 
-3. Create the cover and visual identity.
+4. Create the cover and visual identity.
    - In `beautify` mode, create a cover unless the user explicitly opts out.
    - Default to `1200x400` SVG. Use `1200x320` for compact technical projects
      and `1200x480` for proof-rich showcases.
-   - When no style is selected, recommend exactly three suitable presets from
-     `references/style-catalog.md`, explain each in one sentence, and ask the
-     user to choose. Auto-select only when the user says to decide automatically.
-   - Use exactly one style preset. Do not blend multiple visual systems.
+   - When no direction is selected, recommend exactly three evidence-led
+     directions and ask the user to choose. Auto-select only when the user says
+     to decide automatically.
+   - Choose one coherent direction. Adapt one style seed to the project instead
+     of applying a fixed template or mixing unrelated decorative traits.
    - Use `scripts/render_cover.py` for deterministic exact-text SVG covers.
    - If generated imagery is needed, generate only the subject, texture, or
      background. Add project names, commands, metrics, and labels through SVG.
    - Read `references/cover-system.md` before creating or reviewing a cover.
 
-4. Add proof and explanation.
+5. Add proof and explanation.
    - Prefer real screenshots, outputs, input/output comparisons, terminal
      captures, or diagrams over decorative images.
    - Use SVG for exact diagrams and coordinated section transitions; use
      Mermaid for relationships that benefit from maintainable text source.
    - Keep explanations and commands in Markdown so they remain searchable and
      copyable.
 
-5. Validate and deliver.
+6. Validate and deliver.
    - Run `scripts/check_readme.py <repository>`.
    - Review factual claims against the ledger and `references/fact-check.md`.
    - Apply the GitHub rendering rules in `references/github-rendering.md`.
@@ -92,8 +105,11 @@ to the run.
 - The first screen communicates one concrete promise and one real proof.
 - The cover uses exact, readable text and survives narrow rendering.
 - The title, palette, motifs, and proof feel native to this repository.
+- Removing the project name would not make the visual fit an unrelated project.
 - Claims, commands, paths, versions, ports, and public interfaces match source.
 - Images have meaningful alt text and do not replace essential body content.
 - Relative paths and heading anchors resolve.
 - The result remains useful with images disabled.
 - The user can review every change before anything is published.
+- Do not place README Refiner branding in user assets by default; attribution is
+  optional and belongs outside the project hero.

skills/refine-readme/references/cover-system.md

@@ -22,6 +22,8 @@ strong symbolic or typographic identities. Keep all factual text in SVG source.
 
 Use real screenshots, terminal output, generated results, or prompt cards inside
 a deterministic SVG frame. Do not invent dashboard data or polished outputs.
+Use a single-board hero only when the proof remains readable at the target
+GitHub width. Otherwise make the cover simple and place proof immediately below.
 
 ### Hybrid generated subject
 
@@ -37,6 +39,8 @@ place it under exact SVG typography. Preserve a source prompt and editable SVG.
 - Use no more than one short supporting line in the cover.
 - Avoid tiny fake UI, dense diagrams, long feature lists, and decorative badges.
 - Test the cover on light and dark GitHub themes and near 360 CSS pixels wide.
+- Keep project attribution separate from tool attribution. User covers contain
+  no README Refiner branding or watermark by default.
 
 ## Required checks