docs: refresh launch artifacts and bump guide versions for v2.1.0

.claude/agents/docs-freshness.md

@@ -0,0 +1,131 @@
+---
+name: docs-freshness
+description: "Checks documentation freshness and suggests PitchDocs commands to fix staleness. Launch when docs-awareness rule detects documentation moments, after version bumps, or before releases. Does NOT modify docs — only reports and suggests."
+model: inherit
+color: cyan
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Docs Freshness Agent
+
+You are a read-only documentation freshness checker. Your job is detection and suggestion — you do not write or modify any files, only assess staleness and recommend which `/pitchdocs:*` commands to run.
+
+## When You Are Launched
+
+You are typically launched in response to:
+- The **docs-awareness** rule detecting a documentation moment (version bump, new feature, release prep)
+- A user asking "are my docs up to date?" or similar
+- Before a release to check documentation coverage
+
+## Workflow
+
+### Step 1: Detect Project Type
+
+```bash
+# Find the project manifest
+ls package.json pyproject.toml Cargo.toml go.mod setup.py setup.cfg 2>/dev/null
+```
+
+Extract the current version and project name from the manifest. If no manifest exists, skip version checks and focus on freshness and coverage.
+
+### Step 2: Check Version Alignment
+
+Compare the version in the project manifest against references in documentation:
+
+```bash
+# Extract version from manifest
+grep -o '"version":\s*"[^"]*"' package.json 2>/dev/null || \
+grep -o 'version\s*=\s*"[^"]*"' pyproject.toml 2>/dev/null
+
+# Check if README references a different version
+grep -n 'v[0-9]\+\.[0-9]\+\.[0-9]\+' README.md 2>/dev/null
+```
+
+Flag any version mismatch between the manifest and README/CHANGELOG badges or text.
+
+### Step 3: Check Changelog Coverage
+
+```bash
+# List recent tags
+git tag --sort=-creatordate | head -10
+
+# Find latest version referenced in CHANGELOG
+grep -m 5 '## \[' CHANGELOG.md 2>/dev/null
+```
+
+Compare git tags against CHANGELOG entries. Flag tags that have no corresponding CHANGELOG section.
+
+### Step 4: Check Documentation Freshness
+
+```bash
+# Last commit touching README
+git log -1 --format='%H %ci' -- README.md 2>/dev/null
+
+# Last commit touching source code (excluding docs)
+git log -1 --format='%H %ci' -- '*.ts' '*.js' '*.py' '*.go' '*.rs' '*.json' ':!package-lock.json' ':!CHANGELOG.md' ':!README.md' ':!docs/*' 2>/dev/null
+
+# Count commits between README update and HEAD
+git rev-list --count "$(git log -1 --format=%H -- README.md)"..HEAD 2>/dev/null
+```
+
+Flag if documentation is significantly behind source code (more than 10 commits or 1 tagged release).
+
+### Step 5: Check Structural Coverage
+
+```bash
+# Check for expected documentation files
+ls README.md CHANGELOG.md CONTRIBUTING.md SECURITY.md CODE_OF_CONDUCT.md LICENSE llms.txt docs/ 2>/dev/null
+```
+
+Flag missing standard documentation files that a public repository should have.
+
+If `llms.txt` exists, verify referenced files still exist:
+```bash
+# Extract file paths from llms.txt and check they exist
+grep -oP '(?<=: )\S+\.\w+' llms.txt 2>/dev/null | while read -r f; do [ ! -f "$f" ] && echo "MISSING: $f"; done
+```
+
+### Step 6: Report with Suggestions
+
+Output a structured freshness report:
+
+```
+## Documentation Freshness Report
+
+### Stale
+- [file] — [what's stale] ([how far behind])
+  -> Run `[specific /pitchdocs:* command]` to fix
+
+### Missing
+- [file] — [why it should exist]
+  -> Run `[specific /pitchdocs:* command]` to create
+
+### Fresh
+- [file] — [evidence of freshness] (checkmark)
+```
+
+## Command Suggestion Map
+
+| Finding | Suggested Command |
+|---------|-------------------|
+| README version mismatch or stale content | `/pitchdocs:doc-refresh` |
+| CHANGELOG missing recent tag entries | `/pitchdocs:changelog --from-tag [last-tag]` |
+| README feature count doesn't match codebase | `/pitchdocs:features audit` |
+| Missing README entirely | `/pitchdocs:readme` |
+| Missing CHANGELOG | `/pitchdocs:changelog` |
+| Missing CONTRIBUTING/SECURITY/CODE_OF_CONDUCT | `/pitchdocs:docs-audit fix` |
+| Stale or missing llms.txt | `/pitchdocs:llms-txt` |
+| Stale user guides | `/pitchdocs:user-guide` |
+| General multi-file staleness | `/pitchdocs:doc-refresh` |
+
+## Scope Limits
+
+- **Read-only** — do not modify any files. Your job is reporting, not fixing.
+- **Quick checks only** — do not run deep quality analysis. That is the `docs-reviewer` agent's job.
+- **Suggest specific commands** — always map findings to a concrete `/pitchdocs:*` command.
+- **Safe to run multiple times** — no state, no side effects, no loop prevention needed.
+- **Do not guess** — if you cannot determine staleness with confidence, report it as "unclear" rather than flagging a false positive.

.claude/rules/docs-awareness.md

@@ -0,0 +1,27 @@
+# Documentation Awareness
+
+When working on a project with PitchDocs installed, recognise documentation-relevant moments and suggest the appropriate command. This is advisory — never block work, just surface the right tool at the right time.
+
+## Documentation Trigger Map
+
+| You Notice | Suggest | Why |
+|-----------|---------|-----|
+| New feature added (new exports, commands, routes, API endpoints) | `/pitchdocs:features audit` then `/pitchdocs:readme` | README features section may be out of date |
+| Workflow or CLI args changed | `/pitchdocs:user-guide` to refresh guides | User guides may reference old behaviour |
+| Version bump or new git tag | `/pitchdocs:doc-refresh` | Changelog, README metrics, and guides need updating |
+| Release prep or changelog discussion | `/pitchdocs:changelog` then `/pitchdocs:launch` | Ship release notes and promotion content together |
+| Merging a release-please PR | Remind: run activation evals first (`Actions → Activation Evals → Run workflow`) | Confirm skill activation hasn't regressed (target 80%+) |
+| Project going public (no README or thin README) | `/pitchdocs:readme` | First impressions — generate the full marketing framework |
+| Missing docs detected (no `docs/guides/`, no llms.txt) | `/pitchdocs:docs-audit` | Identify all documentation gaps at once |
+| User asks "why should someone use this?" or discusses positioning | `/pitchdocs:features benefits` | Surface the two-path user benefits extraction (auto-scan or conversational) |
+| README section growing beyond 2 paragraphs or 8-row table | Suggest delegating to `docs/guides/` | Lobby Principle — keep README scannable |
+| User mentions "talk it out" or wants to explain their project's value | `/pitchdocs:features benefits` (conversational path) | The 4-question interview produces the most authentic user benefits |
+| User asks "are my docs up to date?" or similar | Launch the `docs-freshness` agent | Quick triage with specific command suggestions |
+| Session start in a project with PitchDocs activated | Launch the `docs-freshness` agent | Quick freshness check before diving into work |
+
+## When NOT to Suggest
+
+- During debugging, testing, or CI troubleshooting — stay focused on the immediate problem
+- When the user is mid-flow on a complex coding task — wait for a natural pause
+- When the same suggestion was already made this session — don't repeat
+- For trivial code changes (typos, formatting) that don't affect documentation

.claude/skills/feature-benefits/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-benefits
-description: Systematic codebase scanning for features and evidence-based feature-to-benefit translation. Extracts what a project does from its code and translates it into what users gain. Use when generating README features tables, auditing feature coverage, or building benefit-driven documentation.
+description: Systematic codebase scanning for features and evidence-based feature-to-benefit translation. Extracts what a project does from its code and translates it into what users gain — generates features and benefits sections, "Why [Project]?" content, and feature audit reports. Use when writing a features table for a README, extracting features from code, auditing feature coverage, or answering "why should someone use this project?".
 version: "1.0.0"
 ---
 

AGENTS.md

@@ -13,7 +13,7 @@ Skills are loaded on-demand to provide deep reference knowledge. Each lives at `
 | Skill | What It Provides |
 |-------|-----------------|
 | `public-readme` | README structure with the Daytona/Banesullivan marketing framework — hero template, value proposition, quickstart with Time to Hello World targets, features with evidence-based benefits. Companion `SKILL-reference.md` has logo guidelines, registry badges, use-case framing, and visual element guidance (loaded on demand) |
-| `feature-benefits` | 7-step codebase scanning workflow with feature-to-benefit translation across 5 categories (time saved, confidence gained, pain avoided, capability unlocked, cost reduced). Companion `SKILL-signals.md` has detailed signal category scan lists, JTBD mapping, persona inference, conversational path prompts, and per-ecosystem pattern libraries (loaded on demand) |
+| `feature-benefits` | 7-step codebase scanning workflow — extracts concrete features from code, translates to benefit-driven language across 5 categories (time saved, confidence gained, pain avoided, capability unlocked, cost reduced). Generates features and benefits sections, "Why [Project]?" content, and feature audit reports. Companion `SKILL-signals.md` has detailed signal category scan lists, JTBD mapping, persona inference, conversational path prompts, and per-ecosystem pattern libraries (loaded on demand) |
 | `changelog` | Keep a Changelog format with language rules that rewrite conventional commits into user-facing benefit language. Maps `feat:` to Added, `fix:` to Fixed, etc. |
 | `roadmap` | Roadmap structure from GitHub milestones with emoji status indicators, mission statement, and community involvement section |
 | `pitchdocs-suite` | Full 20+ file inventory (README, CONTRIBUTING, CHANGELOG, CODE_OF_CONDUCT, SECURITY, AI context files, issue templates, PR templates, and more), GitHub metadata guidance, visual assets, licence selection framework, and ready-to-use templates |

CHANGELOG.md

@@ -9,31 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-* **SKILL.md version mismatch** — Root marketplace entry said `1.19.3` while plugin.json said `2.1.0`. release-please does not update SKILL.md frontmatter; version now synced manually.
-* **docs-verify broken companion references** — Three references to `SKILL-extended.md` (renamed to `SKILL-reference.md` during v2.0.0 token budget split) now point to the correct file.
-* **Hook exit codes** — `content-filter-guard.sh` used `exit 1` after `"decision": "block"` JSON. Changed to `exit 0` so Claude Code treats it as a clean block, not a hook crash. Tests updated to match.
-* **docs-verify command dimension count** — Said "5 dimensions" but the skill defines a 6-dimension scoring rubric. Now says "6 dimensions".
-* **doc-refresh stale ai-context reference** — Skill description and command both referenced `ai-context` as a delegated skill, but it moved to ContextDocs in v2.0.0. Updated to reference ContextDocs directly.
-* **CLAUDE.md component counts** — Corrected agent count (PitchDocs provides 4, not 5 — context-updater is from ContextDocs) and rule count (3 auto-loaded, not 4 — context-quality.md is from ContextDocs).
-* **Hook installed-by comment** — Updated from `/context-guard install` (pre-ContextDocs) to `/pitchdocs:activate install strict`.
-* **RESULTS.md stale metadata** — Version updated from 1.19.3 to 2.1.0, agent count from 3 to 5.
-* **TTHW circular reference** — `public-readme` skill pointed to `doc-standards` for TTHW targets, which pointed back to `public-readme`. Added the actual targets table to `SKILL-reference.md` and fixed both pointers.
-* **llms.txt orphans** — Added missing reference for `feature-benefits/SKILL.md` and updated `user-guides/SKILL-templates.md` description. Fixed "15 commands" → "16 commands" in command reference link.
-
-### Added
-
-* **3 new activation eval test cases** — `/pitchdocs:geo`, `/pitchdocs:visual-standards`, and a natural language GEO trigger. Eval suite now has 24 test scenarios (was 21).
-* **API Reference Check in docs-audit** — The `/pitchdocs:docs-audit` command now checks for API reference documentation and recommends loading the `api-reference` skill when a public API is detected (#41).
-* **Agent frontmatter** — Added `model: inherit` and `color` fields to `docs-freshness` (cyan) and `context-updater` (magenta) agents for consistency with the 3 pipeline agents.
-* **TTHW targets table** — Added Time to Hello World targets by project type to `public-readme/SKILL-reference.md` so quick start sections have concrete benchmarks.
+* **Plugin review issues from v2.1.0 release** — Version sync in skill frontmatter, hook exit codes, stale references to moved skills, and evaluation test coverage now properly aligned with production state.
 
 ### Removed
 
-* **`skill-authoring` skill** — Removed. This was a meta-guide about token budgets for writing Claude Code skills, which is out of scope for PitchDocs (a public-facing documentation plugin). Skill authoring guidance belongs in the `plugin-dev` plugin. Skill count: 16 → 15. Closes #40.
+* **`skill-authoring` skill** — This meta-guide about token budgets for writing Claude Code skills is out of scope for PitchDocs (a documentation plugin). Skill authoring guidance belongs in the `plugin-dev` plugin instead.
 
-### Changed
+### Security
 
-* **Roadmap skill description** — Now says "GitHub, GitLab, or Bitbucket" instead of just "GitHub Projects" so the skill activates correctly for non-GitHub repos.
+* **GitHub Actions supply chain security** — All third-party GitHub Actions are now pinned to specific commit SHAs instead of mutable version tags, preventing malicious updates. CODEOWNERS file added for transparent code review governance.
 
 ## [2.1.0](https://github.com/littlebearapps/pitchdocs/compare/v2.0.0...v2.1.0) (2026-03-12)
 

README.md

@@ -39,7 +39,7 @@
     </td>
     <td align="center" width="200">
       <a href="https://github.com/littlebearapps/outlook-assistant">
-        <img src="https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/assets/outlook-assistant-logo-icon.svg" width="80" alt="Outlook Assistant logo" /><br />
+        <img src="https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/assets/outlook-assistant-logo-icon.png" width="80" alt="Outlook Assistant logo" /><br />
         <strong>Outlook Assistant</strong>
       </a><br />
       <sub>MCP server for Outlook email, calendar, and contacts</sub>