feat: v2.3.0 — ecosystem refresh, Agent Skills compliance, FAQ rename

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pitchdocs",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Generate high-quality public-facing repository documentation with a marketing edge. Creates READMEs that sell, changelogs that communicate value, roadmaps from GitHub milestones, and audits your docs completeness. Uses benefit-driven language, GEO-optimised structure, progressive disclosure, and the Banesullivan 4-question framework.",
   "author": {
     "name": "Little Bear Apps",
@@ -29,6 +29,7 @@
     "hooks",
     "gitlab",
     "bitbucket",
-    "multi-platform"
+    "multi-platform",
+    "agent-skills"
   ]
 }

.claude/rules/docs-awareness.md

@@ -1,7 +1,15 @@
+---
+name: docs-awareness
+description: Documentation trigger map — surface PitchDocs commands at the right documentation moments (file edits, version bumps, release prep). Advisory; never blocks work.
+paths: README.md, CHANGELOG.md, ROADMAP.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, docs/**, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/**, .github/PULL_REQUEST_TEMPLATE.md, FUNDING.yml
+---
+
 # 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.
 
+> **Path scoping:** This rule's `paths:` frontmatter scopes auto-activation to documentation files. On Claude Code versions that honour the field, the trigger map only fires when one of those files is edited; conceptual triggers (version bumps, release prep, "release-please discussion") still apply when Claude is reasoning over the broader workspace context. On older Claude Code versions, the rule loads globally as before.
+
 ## Documentation Trigger Map
 
 | You Notice | Suggest | Why |

.claude/skills/changelog/SKILL.md

@@ -1,12 +1,27 @@
 ---
 name: changelog
 description: Generates user-friendly changelogs from git history using conventional commits. Writes entries in benefit language ("You can now..." not "Refactored internal..."). Follows Keep a Changelog format. Use when creating or updating CHANGELOG.md.
+argument-hint: "[version or 'full' for complete history]"
+allowed-tools: Read Glob Grep Bash Write Edit mcp__github__list_releases mcp__github__list_commits mcp__github__list_tags mcp__github__list_pull_requests
 version: "1.0.0"
 upstream: "keep-a-changelog@1.1.1"
 ---
 
 # Changelog Generator
 
+## Invocation
+
+Generate or update CHANGELOG.md using conventional commits and user-benefit language.
+
+1. Load the `doc-standards` rule for tone
+2. If GitHub MCP tools are unavailable (GitLab/Bitbucket), gather equivalent data via `glab` CLI, REST API, or git history. Load `platform-profiles` for compare URL patterns.
+3. Analyse git history — parse conventional commits, identify tagged releases, map to issues/PRs
+4. Classify changes into Keep a Changelog categories
+5. Rewrite commit messages in user-benefit language
+6. Write to `CHANGELOG.md`, preserving existing entries when updating
+
+**Arguments:** No arguments → updates `[Unreleased]` only. Version (e.g. `1.3.0`) → entry for that tag. `full` → regenerate the entire changelog from all tags.
+
 ## Format: Keep a Changelog
 
 Follow [keepachangelog.com](https://keepachangelog.com/) with marketing-friendly language.

.claude/skills/doc-refresh/SKILL.md

@@ -1,11 +1,36 @@
 ---
 name: doc-refresh
 description: Orchestrates documentation updates after version bumps, feature additions, or periodic maintenance. Analyses git history since the last release, identifies which docs are affected, and delegates to existing skills (changelog, feature-benefits, docs-verify, llms-txt, user-guides) for selective refresh. Delegates AI context updates to ContextDocs if installed. Use when releasing a new version or refreshing stale docs.
+argument-hint: "[version, range (v1.5.0..v1.7.0), plan, changelog, readme, guides, context, release-notes, full]"
+allowed-tools: Read Glob Grep Bash Write Edit WebFetch mcp__github__list_releases mcp__github__list_commits mcp__github__list_tags mcp__github__list_pull_requests mcp__github__list_issues mcp__github__get_file_contents
 version: "1.0.0"
 ---
 
 # Doc Refresh
 
+## Invocation
+
+Refresh existing documentation to reflect the current state of the codebase. Analyses git history since the last release, identifies what changed, and surgically updates only the affected docs.
+
+1. Load the `doc-standards` rule for tone and quality
+2. If GitHub MCP tools are unavailable (GitLab/Bitbucket), gather data via `glab` CLI, REST API, or git history. Load `platform-profiles` for CI/CD equivalents.
+3. Detect the change boundary (latest tag, provided version, or range)
+4. Parse conventional commits and classify changes by type and doc impact
+5. Detect file-level changes to identify which areas changed
+6. Build a refresh plan mapping changes to doc updates
+7. Execute the plan, loading affiliated skills as needed: `changelog`, `feature-benefits`, `user-guides`, ContextDocs (if installed) for AI context drift, `llms-txt`, `package-registry`, `docs-verify`
+8. Report what was updated and the quality score
+
+**Arguments:**
+- No arguments → detect latest tag, refresh all affected docs
+- Version (e.g. `1.7.0`) → refresh docs for a specific release
+- Range (e.g. `v1.5.0..v1.7.0`) → refresh for a range
+- `plan` → dry run; report what needs refreshing
+- `changelog`, `readme`, `guides`, `context`, `release-notes` → scoped refresh
+- `full` → refresh everything regardless of detected changes
+
+**Release-Please integration:** run `/doc-refresh` before merging a release-please PR to enhance CHANGELOG entries with benefit language and refresh README features and metrics. release-please owns version strings; `/doc-refresh` owns prose, features, metrics, user guides, and llms.txt.
+
 ## Philosophy
 
 Generation is solved — PitchDocs handles that. Maintenance is the unsolved problem. After the initial docs suite is created, every release needs a coordinated update: CHANGELOG entries enhanced with benefit language, README features refreshed, user guides amended, AI context files synced, and llms.txt kept current.

.claude/skills/docs-verify/SKILL.md

@@ -1,11 +1,29 @@
 ---
 name: docs-verify
 description: Validates documentation quality and freshness — checks for broken links, stale content, llms.txt sync, image issues, heading hierarchy, and badge URLs. Runs locally or in CI. Use to catch documentation decay before it reaches users.
+argument-hint: "[links|freshness|ci|score] or --min-score N"
+allowed-tools: Read Glob Grep Bash
 version: "1.5.0"
 ---
 
 # Documentation Verifier
 
+## Invocation
+
+Validate that documentation remains accurate, linked, and fresh over time. Catches broken links, stale content, and llms.txt drift before they reach users.
+
+1. Scan all Markdown files in the repository
+2. Run the requested checks (or all checks if no arguments)
+3. Report findings with severity levels and a numeric quality score (0–100)
+
+**Arguments:**
+- No arguments → run all checks
+- `links` → link validation only
+- `freshness` → staleness check only (git blame-based)
+- `ci` → all checks, CI-friendly format (exit code 1 on errors, file:line)
+- `score` → run all checks, output the quality score only
+- `--min-score N` → fail if quality score falls below N (CI gate)
+
 ## Philosophy
 
 Generating documentation is a solved problem. **Preventing documentation decay** is not. This skill validates that generated docs remain accurate, linked, and fresh over time.

.claude/skills/llms-txt/SKILL.md

@@ -1,11 +1,26 @@
 ---
 name: llms-txt
 description: Generates llms.txt and llms-full.txt files following the llmstxt.org specification. Provides LLM-friendly content curation for AI coding assistants (Cursor, Windsurf, Claude Code) and AI search engines. Use when generating or updating llms.txt for a repository.
+argument-hint: "[path or 'full' to include llms-full.txt]"
+allowed-tools: Read Glob Grep Bash Write Edit
 version: "1.0.0"
 ---
 
 # llms.txt Generator
 
+## Invocation
+
+Generate `llms.txt` (and optionally `llms-full.txt`) following the [llmstxt.org](https://llmstxt.org/) specification. Provides AI coding assistants and search engines with a structured index of project documentation.
+
+1. Load the `doc-standards` rule for description quality
+2. Read the project manifest (`package.json`, `pyproject.toml`, etc.) for name and description
+3. Scan the repository for documentation files: README, `docs/`, API reference, guides, examples, supporting (CONTRIBUTING, CHANGELOG, SECURITY, CODE_OF_CONDUCT, ROADMAP, LICENSE)
+4. Write benefit-focused descriptions for each file (not just file names)
+5. Assemble `llms.txt`: H1 from project name, blockquote summary, H2 sections by category, `## Optional` for supporting files
+6. If `full` argument: concatenate all referenced files into `llms-full.txt`
+
+**Arguments:** No arguments → `llms.txt` only. `full` → both `llms.txt` and `llms-full.txt`. Path argument → generate for a specific project directory.
+
 Generate structured, LLM-friendly content indexes following the [llmstxt.org](https://llmstxt.org/) specification.
 
 ## Background

.claude/skills/package-registry/SKILL.md

@@ -79,17 +79,20 @@ This section covers documentation-relevant aspects. The plugin does NOT create p
 
 - **OIDC trusted publishing went GA July 2025** — replaces long-lived tokens entirely
 - Classic tokens permanently revoked December 2025; granular tokens max 90 days
+- **Minimum versions (as of 2026):** npm CLI ≥ 11.5.1 and Node ≥ 22.14.0 — flag projects on older toolchains
 - Publishing with `--provenance` flag adds a **Sigstore badge** on npmjs.com linking to the exact source commit and build workflow
+- Provenance auto-generates from **GitHub Actions** and **GitLab CI**; **CircleCI is not supported**, and **private repositories cannot generate provenance**
 - Requires `id-token: write` permission in GitHub Actions
 - `repository.url` in package.json must exactly match the GitHub repo URL (case-sensitive)
 
 ### PyPI Trusted Publishing
 
 - **Trusted Publisher since April 2023** — first major registry to support OIDC
-- **Digital attestations (PEP 740) since November 2024** — Sigstore signing for package files
+- **PEP 740 digital attestations now default** — `pypa/gh-action-pypi-publish` auto-generates them on every publish via Trusted Publishing with no extra configuration. ~20k packages currently covered (see [are-we-pep740-yet](https://trailofbits.github.io/are-we-pep740-yet/))
 - "Verified details" sidebar badge appears automatically when trusted publisher is configured
 - Repository URL in `[project.urls]` must match the GitHub repo for verification
 - `pypa/gh-action-pypi-publish` handles publishing when configured as a trusted publisher
+- See [PEP 740](https://peps.python.org/pep-0740/) and [PyPI attestations docs](https://docs.pypi.org/attestations/) for the attestation manifest format
 
 ### What to Audit (Not Configure)
 

.claude/skills/pitchdocs-suite/SKILL-templates.md

@@ -114,7 +114,7 @@ After fetching, use Edit tool to replace these placeholders:
 - `[INSERT CONTACT METHOD]` — project contact email or reporting URL
 - Verify the "Enforcement" section matches the project's governance structure
 
-**Why v3.0:** Clearer language, less US-centric phrasing, "Addressing and Repairing Harm" section aligned with restorative justice principles. Always use v3.0 for new projects.
+**Why v3.0:** Clearer language, less US-centric phrasing, "Addressing and Repairing Harm" section aligned with restorative justice principles. Always use v3.0 for new projects. **High-profile validation:** Django completed migration to v3.0 on 2026-04-15 — a strong credibility signal for the v3.0 default.
 
 **Fallback:** If the URL is unreachable, direct the user to https://www.contributor-covenant.org/version/3/0/code_of_conduct/ and ask them to download manually.
 
@@ -154,6 +154,8 @@ After fetching or creating the starter file, use Edit tool to customise in small
 
 ## .github/ISSUE_TEMPLATE/bug_report.yml
 
+> **GitHub Issue Forms updates (2026):** As of 2026-03-05, Issue Forms support an `attachments` field for required logs/screenshots/crash reports, and template files are sorted alphabetically in the picker — name files with leading numbers (`01-bug_report.yml`, `02-feature_request.yml`) if you need a specific order. Required fields now also work in **private repos**. Separately, the new "Issue Fields" structured-metadata feature entered public preview on 2026-03-12 — preview only; do not recommend yet for canonical templates.
+
 ```yaml
 name: Bug Report
 description: Report a bug to help us improve
@@ -215,6 +217,13 @@ body:
       label: Relevant logs
       description: Paste any relevant error messages or logs.
       render: shell
+  - type: attachments
+    id: artefacts
+    attributes:
+      label: Logs, screenshots, or crash reports
+      description: Drag and drop files (logs, screenshots, video) so we have everything needed to reproduce.
+    validations:
+      required: false
 ```
 
 ## .github/ISSUE_TEMPLATE/feature_request.yml
@@ -306,9 +315,18 @@ Closes #
 github: [username]
 # ko_fi: username
 # open_collective: project-name
+# patreon: project-name
+# polar: org-or-user        # developer-focused funding (added to GitHub's allowlist)
+# liberapay: project-name
+# tidelift: npm/package-name # npm:foo, pypi:foo, etc.
+# buy_me_a_coffee: username
+# thanks_dev: u/username     # GitHub Sponsors alternative
+# issuehunt: org/repo
 # custom: ["https://example.com/donate"]
 ```
 
+GitHub displays funding links from this file as a "Sponsor" button on the repository page. See [GitHub's customizing-your-repository docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository) for the full list of supported keys.
+
 ## SUPPORT.md
 
 ```markdown

.claude/skills/roadmap/SKILL.md

@@ -1,11 +1,26 @@
 ---
 name: roadmap
 description: Generates ROADMAP.md from project milestones, issues, and boards (GitHub, GitLab, or Bitbucket). Structures content with mission statement, current milestone progress, upcoming milestones, and community involvement section. Use when creating or updating a project roadmap.
+argument-hint: "[milestone name or 'full' for complete roadmap]"
+allowed-tools: Read Glob Grep Bash Write Edit mcp__github__list_issues mcp__github__list_pull_requests mcp__github__list_releases mcp__github__list_tags mcp__github__search_issues
 version: "1.0.0"
 ---
 
 # Roadmap Generator
 
+## Invocation
+
+Generate or update ROADMAP.md from milestones, issues, and project boards.
+
+1. Load the `doc-standards` rule for tone
+2. If GitHub MCP tools are unavailable (GitLab/Bitbucket), gather data via `glab` CLI, REST API, or git history. Load `platform-profiles` for CLI equivalents.
+3. Gather data: milestones and their issues, issues labelled `enhancement`/`feature`, recent releases/tags, README/manifest for mission statement
+4. Structure into current, upcoming, and completed milestones
+5. Add mission statement and "How to get involved" section
+6. Write to `ROADMAP.md`
+
+**Arguments:** No arguments → full roadmap. Milestone name → focuses on a specific milestone. `full` → regenerates from scratch.
+
 ## ROADMAP.md Structure
 
 ```markdown

.claude/skills/user-guides/SKILL-reference.md

@@ -13,7 +13,7 @@ Every documentation file in `docs/` should include YAML frontmatter for metadata
 ```yaml
 ---
 title: "Getting Started with PitchDocs"
-description: "Install PitchDocs, generate your first README, and explore all 16 commands."
+description: "Install PitchDocs, generate your first README, and explore the 14 user-invocable slash commands."
 type: how-to          # tutorial | how-to | reference | explanation
 ---
 ```

.claude/skills/visual-standards/SKILL.md

@@ -1,11 +1,23 @@
 ---
 name: visual-standards
 description: Visual formatting standards for repository documentation — emoji heading prefixes, horizontal rules, TOC anchors, callouts, screenshots (device dimensions, HTML patterns, captions, shadows), and image optimisation. Load when generating READMEs with visual elements or working with screenshots.
+argument-hint: "[topic: 'screenshots', 'emoji', 'captions', or general]"
+allowed-tools: Read Glob Grep
 version: "1.0.0"
 ---
 
 # Visual Standards
 
+## Invocation
+
+Load visual formatting reference for emoji heading prefixes, horizontal rules, TOC anchors, callouts, screenshot dimensions, HTML patterns, captions, shadows, and image optimisation.
+
+**Use when:**
+- Adding screenshots or demo GIFs to a README
+- Setting up emoji heading prefixes for a long README
+- Checking device-specific capture dimensions
+- Working with captions, shadows, or image annotations
+
 ## Emoji Heading Prefixes
 
 Use a single emoji before each H2 heading to create visual anchors when scrolling.
@@ -71,3 +83,20 @@ Reserve GitHub callout syntax for GitHub-only documents (issue templates, PR tem
 ## Screenshots & Device Images
 
 For device-specific capture dimensions, HTML display patterns, retina handling, annotation conventions, captions, shadows/borders, browser chrome, file naming, and optimisation guidance, load `SKILL-reference.md` from this skill directory.
+
+## Diagrams (Mermaid)
+
+Mermaid renders natively on GitHub and GitLab; npm and PyPI strip it. For multi-renderer READMEs, **pre-render to SVG/PNG and reference the static asset** — the Mermaid source can live alongside in `docs/diagrams/` for editability.
+
+| Diagram type | When to use |
+|--------------|-------------|
+| `flowchart` | Decision trees, control flow, data pipelines |
+| `sequenceDiagram` | API call traces, request/response timing |
+| `classDiagram` | Type relationships, ORM mappings |
+| `stateDiagram-v2` | State machines, lifecycle docs |
+| `gitGraph` | Branch strategy / release flow visualisation |
+| `wardleyMap` | Strategy diagrams — capability evolution from genesis → custom → product → commodity (Mermaid 11+) |
+
+**Styling:** Mermaid 2026's "neo look" refresh applies cleaner defaults to flowchart, class, sequence, state, and gitGraph diagrams. To opt into the new defaults explicitly, set `%%{init: {"look": "neo"}}%%` at the top of the diagram block. To keep the classic look across versions, use `"look": "classic"`.
+
+**GitHub theme handling:** GitHub auto-syncs the Mermaid theme to dark mode **only when no `%%{init}%%` theme is set**. If you pin a theme, light/dark mode users see the same colours — verify both in preview before merging.