@lovehlmmm/primekit 1.0.0

package/skills/docs/references/agents-workflow.md

@@ -0,0 +1,268 @@
+# Agents Workflow
+
+Load for `/pk:docs agents`. Mine bounded git and CI history for recurring
+failure modes and non-derivable gotchas, and — with `--source` — current
+source-code markers, then distill confirmed rules into the **root** agent
+context file (`CLAUDE.md`/`AGENTS.md`).
+
+The context file is **behavioral memory**, not a codebase map. Rules take the
+form of "DO X" / "DON'T Y" that raise agent success rate, cut trial-and-error,
+and cover project best practices and edge cases. Anything an agent can learn
+by running `ls`, `grep`, or reading a config file is out of scope — see the
+"Anti-patterns" section.
+
+This workflow operationalizes the "add on failure, not up front" principle in
+`agent-context-rules.md`. Every rule it produces still passes the keep-or-cut
+filter and write/don't-write table in that file; this workflow adds mining and
+ranking only, and never invents a second filter.
+
+Before proposing or applying a test-related root-context edit, load and apply
+`references/practical-principles-for-setting-up-and-running-tests.md`. It does
+not bypass the evidence, keep-or-cut, placement, or user-confirmation gates.
+
+## Hard constraints
+
+- **Read-only mining.** No git mutation. No CI re-runs. No settings/hook edits
+  (recommend-only, per `agent-context-rules.md`).
+- **Bounded window.** Default: 90 days OR 300 commits (whichever is smaller),
+  200 CI runs. Positional override: `agents 30d`, `agents 500`.
+  Never open-ended: old history describes code that no longer exists.
+- **Confirm before write.** Nothing lands in the agent context file without
+  explicit user approval on the proposed diff.
+- **`--advice` is implied.** The Kongming review pass is built into step 5.
+  A separate `--advice` flag is redundant here.
+- **`--dry-run` stops after step 3.** Reports mined signals and watchlist,
+  makes no rule proposals, spawns no advisor, writes no file.
+- **`--source` is additive.** Layers `pk:scout` source-tree mining onto git/CI
+  mining; never replaces them or their gates. Scout runs read-only: no
+  generators, no tests. Composes with `--dry-run` and `--audit`.
+
+## 1. Gate and bounds
+
+Run the parent skill's opening gate (bounded). Confirm:
+
+- repository and current branch;
+- window (defaults above, or user-supplied positional);
+- whether `gh` is authenticated (`gh auth status`); if not, degrade to
+  git-only and report "CI signals skipped: gh unauthenticated";
+- current root agent context file + any path-scoped rules already in place
+  (read them now — dedupe and conflict-check depend on this);
+- whether `--source` is set; if so, note vendored, generated, and
+  dependency directories to exclude from scout patterns.
+
+## 2. Signal mining
+
+Use `git` for local history, `gh` for CI and PR reviews when available.
+Exclude merge commits and mass renames when counting incidents
+(`git log -M --no-merges --diff-filter=ACDM`).
+
+### Git
+
+| Signal | Command (illustrative) | Rule class |
+|---|---|---|
+| Reverts | `git log --since=<w> --grep='^Revert' --oneline` + touched files | Deny-list, definition of done |
+| Fix-of-fix chains | `git log --since=<w> -iE --grep='fix (again\|properly\|actually)\|really fix\|follow-?up\|typo in prev'` | Missing verification step |
+| Fix-density hotspots | `git log --since=<w> --grep='^fix' --name-only --pretty=format: \| sort \| uniq -c \| sort -rn` | Non-derivable gotcha on file/module |
+| CI-repair after merge | commits like `fix ci`, `fix lint`, `fix build` on the integration branch | "Run X before push" (DoD) |
+| Co-change coupling | pair-mine `git log --pretty=%h --name-only`: file pairs that change together but were split across two commits (second commit added the missing half) | "When editing X, also update Y" — the highest-value generator |
+| Commit velocity / size | — | **Skip.** Almost always yields vibe rules that fail the verifiability test |
+
+### CI (via `gh`, degrade gracefully)
+
+- `gh run list --limit 200 --json workflowName,conclusion,headBranch,event,createdAt,displayTitle`
+  → failure-rate and cancelled-rate per workflow.
+- Flakiness: runs whose `run_attempt > 1` passed on a later attempt for the
+  same head SHA (`gh api repos/{owner}/{repo}/actions/runs?per_page=100`).
+- Recurring failure signature: for top failing workflows,
+  `gh run view <id> --log-failed`, cluster by job name + first error line.
+- Long-running jobs → "full suite is slow, use `<filter>`" candidates.
+
+### Source (`--source`, via `pk:scout`)
+
+Only when `--source` is set. Spawn `pk:scout` **once** with the fixed pattern
+query list below, read-only, excluding vendored/generated/dependency dirs
+noted in step 1. Do not force Explore delegation; native search is fine.
+
+| Signal | Pattern (illustrative) | Rule class |
+|---|---|---|
+| Editor-directed imperative in header comments | `-iE 'do not (edit\|modify\|touch\|use)\|generated by\|autogenerated\|source of truth'` | Deny-list / editor guidance |
+| Sync invariants across paired files | `-iE 'keep (in sync\|synchronized) with\|mirror(s)? of\|must match'` | "When editing X, also update Y" |
+| Generated-artifact mapping to owner script | `-iE '^// Code generated\|// GENERATED FILE\|@generated\|do not edit; regenerate with'` | Owner-script pointer |
+| Guarded boundaries (privileged paths, safety walls) | `-iE 'requires elevated\|privileged\|sandbox\|do not run outside\|guarded by'` | Boundary rule |
+| Silent-failure preconditions | `-iE 'must (be set\|be initialized)\|precondition\|assumes\|only valid when'` | Non-derivable gotcha |
+| Skip / quarantine with reason | `-iE '@skip\|xit\(\|skip\(\|// TODO: re-enable when'` (Tier 2) | Test-coverage gotcha |
+| Inverted convention / legacy twin | `-iE 'legacy\|deprecated in favor of\|prefer .* over\|do not use .* use'` (Tier 2) | Convention rule |
+
+Skip from mining: bare `TODO`/`FIXME`/`XXX`/`HACK` markers, redundant
+`@deprecated` annotations already surfaced by tooling, `readonly` keyword
+occurrences, and loud-crash env-var reads the agent can derive from a config
+file.
+
+Cluster raw hits by `(rule class, module/dir)`. Aim for ≤10 clusters → ≤5
+distilled proposals; the same ranking cost tie-breaker applies.
+
+### Optional secondary sources
+
+- PR review comments on ~30 recent merged PRs (when `gh` is authenticated) —
+  reviewers repeatedly correcting the same class of mistake is the highest-
+  quality signal for a rule.
+- `plans/journals/` and `plans/reports/` if present — postmortems already
+  written.
+
+Do **not** re-run tests, re-request CI runs, or open the sandbox to reproduce.
+This is mining, not investigation.
+
+## 3. Signal ranking
+
+Apply all four gates. Missing any one → cut.
+
+1. **Recurrence: ≥3 independent incidents.** Independent = different day *or*
+   different author/PR. A fixup chain on the same day counts as **one** incident.
+   Two incidents → watchlist (chat-only, no file, no proposal). One → drop.
+2. **Preventability.** Would one imperative line read *before* acting have
+   prevented the incident? If prevention requires judgment/context depth, this
+   is not a root-context rule — route it via placement router in step 4.
+3. **Already-enforced test.** Check current live state (lint config, hook,
+   branch protection, CI required checks). If the failure mode is now
+   deterministically blocked, do not write a rule; report "already enforced by
+   `<owner>`".
+4. **Recency decay.** If the signal stops after a rule/enforcement landed,
+   consider it resolved and skip. Compare the incident's last timestamp to the
+   fix's timestamp.
+
+Tie-break by **cost**, not count: protected-branch/release/team-wide CI
+failures outrank local churn. Exclude any incident window dominated by a bulk
+refactor or repository-wide rename.
+
+**Source-signal gates** (only when `--source` produced candidates): replace
+gate 1 with a **corroboration gate** — a source cluster qualifies only when
+one of these holds: (a) the marker appears at ≥2 independent sites in the
+cluster; (b) a code/test guard already relies on the invariant (import,
+assertion, matching test name); or (c) git or CI history in this window
+corroborates the same class of failure at least once. Gates 2 (preventability),
+3 (already-enforced), and 4 (recency) still apply verbatim — a source hit
+already blocked by a linter, hook, or generator regenerate script is out.
+
+**`--dry-run` stops here** and reports raw counts, ranked candidates, and the
+watchlist. No distillation, no advisor, no diff.
+
+## 4. Distillation template
+
+Fill for every candidate that survived ranking. Aim ≤5 candidates per run
+(if more, keep top-5 by cost).
+
+```text
+Signal:     <pattern> — N incidents/anchors: <shas / run-ids / path:line>, window <w>
+Cost:       <what broke, time/CI-minutes lost>
+Behavior:   <the specific wrong action taken>
+Rule:       "<one imperative, verifiable line — exact command/path,
+             no history narration>"
+Placement:  root context file | path-scoped rule
+          | reviewer playbook / standards doc
+          | enforcement snippet (recommend-only)
+Filter:     findable-itself? N | prevents-costly-action? <action>
+          | verifiable? Y | conflicts? <checked-against>
+Cut offer:  <existing line this replaces or makes redundant, if any>
+Confidence: high | medium | low
+```
+
+**Placement router** (a lesson does not automatically belong in the root
+context file):
+
+- imperative, always-apply, blocks a specific action → root context file;
+- applies only to a path or file type → path-scoped rule
+  (see `agent-context-rules.md` "Activation scope");
+- absolute rule ("never push X", "never touch Y") → **recommend** a
+  settings/hook snippet, do not edit `settings.json` or hook files yourself;
+- judgment call or historical scar → reviewer playbook or code standards
+  via `update`, not an `agents` output.
+
+**Forbidden in rule text:** SHA, dates, "we once…", plan/finding IDs,
+uppercase-as-emphasis, and any wording that narrates history. The rule
+describes *future behavior*.
+
+## 5. Kongming review pass — spawn once
+
+Spawn `kongming` a single time with:
+
+- the full candidate set (all templates from step 4);
+- the current root agent context file (verbatim) and any path-scoped rules;
+- the ranked evidence table from steps 2–3;
+- the keep-or-cut filter and write/don't-write table from
+  `agent-context-rules.md`;
+- the current net line budget for the context file.
+
+Ask Kongming to: cut noise, catch conflicts and duplicates against existing
+lines, correct placement mistakes, and propose cut-offers so the net size
+stays bounded. A per-signal spawn is wasted cost and yields inconsistent
+counsel; the value comes from Kongming seeing the whole file and the whole
+candidate set together. Spawn again only when stuck or before an irreversible
+change (matches the existing `--advice` semantics in the parent skill).
+
+## 6. Confirmation
+
+Default: **batch diff**. Present the proposed adds, cut-offers, and
+migrations as a single diff plus the evidence table. The user approves or
+rejects per line in one round. This is the natural extension of
+`agent-context-rules.md` audit-procedure step 3.
+
+With `--audit`: interview one question per rule (keep / cut / fix / migrate),
+same cadence as the existing `--audit` flag.
+
+**Never write unconfirmed changes.**
+
+## 7. Write and verify
+
+- Apply only the confirmed lines.
+- Report the line-count delta. Target net ≤ +10 lines per run; net-negative
+  runs (more cut than added) are a healthy sign.
+- Re-run the conflict check against the file as written.
+- Report: proposed / accepted / rejected / watchlisted / enforcement-recommended
+  counts, plus the exact evidence anchors for each accepted rule (stored in
+  the commit message body, not the rule text).
+
+## Anti-patterns
+
+- Rule sourced from 1–2 incidents (recency bias, one-off flake).
+- Rule that narrates history rather than commanding future behavior.
+- Rule duplicating what a linter, formatter, hook, or branch protection
+  **currently** enforces (check live state, not memory).
+- Derivable rule — anything the agent can learn from `ls`, `grep`, a config
+  file, or a CI log (fails filter question 1).
+- Vibe rule ("be careful with X", "prefer clean code") — fails verifiability.
+- Bloat: adds without cut-offers when the file is already long, or breaching
+  the net budget without user approval.
+- Absolute rule written as uppercase markdown instead of a recommended
+  settings/hook snippet.
+- Judgment call forced into an absolute rule in the root context file
+  instead of routed to a reviewer playbook.
+- Counting churn inside a bulk refactor or rename window without exclusion.
+- Any git or CI mutation during mining.
+- Persisting the watchlist to a new state file (governance machinery). Users
+  who want cross-run trend tracking should route through `pk:journal`.
+- `--source` rule from a single anchor without a code/test guard or git-CI
+  corroboration (fails the corroboration gate).
+- `--source` rule sourced from a vendored, generated, or dependency
+  directory not excluded in step 1.
+- `--source` rule that only paraphrases a linter, formatter, generator, or
+  hook already enforcing the marker.
+- Copying a header comment verbatim into the context file instead of
+  distilling one imperative line describing future behavior.
+- Restating repository structure, module inventory, or command lists mined
+  from source — those fail the keep-or-cut filter regardless of anchor count.
+- Turning a `TODO`/`FIXME`/`HACK` marker into a rule (transient state, not a
+  behavior directive).
+- Running `pk:scout` more than once per invocation, or using it to open a
+  sandbox / run tests / regenerate artifacts.
+
+## Success signals
+
+- ≤5 rules proposed per run, each with ≥3 incident references — or, for
+  `--source` rules, ≥2 anchors backed by a code/test guard or a single
+  git-CI corroboration.
+- User acceptance rate high enough (>50%) to indicate ranking is calibrated.
+- Root context file line-count net change stays inside the budget; some runs
+  are net-negative.
+- Over 2–3 cycles, the mined signal's own frequency falls in the next
+  window — the workflow closes its own feedback loop, measurable by rerunning
+  the mining commands.

package/skills/docs/references/doc-content-rules.md

@@ -0,0 +1,77 @@
+# Doc Content Rules
+
+Load this file before generating or updating documentation. Include the
+relevant ownership, drift-resistance, and authority rules in every docs-manager
+delegate prompt because delegated contexts are isolated.
+
+Root agent context files (`CLAUDE.md`/`AGENTS.md`) are process memory, not
+WHY/WHERE docs; follow `agent-context-rules.md` for those. This file's deletion
+test and drift-resistance rules are the shared spine both operations rely on.
+
+## Ownership Rule
+
+Code owns WHAT and HOW. Docs own only WHY and WHERE.
+
+- WHY: decisions, rejected alternatives, trade-offs, business rules, domain
+  terminology, and constraints code cannot express.
+- WHERE: navigation to entry points, module boundaries, and executable owners.
+
+Never write prose that re-describes implementation behavior. It creates a
+second source of truth that is not executable or testable. Point to source,
+tests, schemas, manifests, generators, or workflows instead.
+
+## The Deletion Test
+
+For every sentence, ask:
+
+1. If an agent read the executable owner, would it learn this anyway? If yes,
+   delete the sentence or replace it with a pointer.
+2. If the team vanished, could this rationale, constraint, or terminology be
+   recovered from the repository? If no, keep and clarify it.
+
+## Drift-Resistance Rules
+
+1. Point, do not paraphrase. Prefer a stable path plus symbol or named heading.
+2. Never copy code, signatures, config bodies, mutable inventories, or command
+   output into prose. An example may remain only when it teaches a decision.
+3. Do not hand-maintain counts, percentages, LOC tables, file trees, or support
+   matrices. Link to their machine owner or provide the command that discovers
+   them.
+4. Distill current rationale into the repository's canonical decision surface.
+   Remove obsolete or superseded prose; Git history preserves the long form.
+5. Every current claim must be either mechanically checkable or a durable
+   decision/domain fact. A claim falsifiable by an implementation rename needs
+   an executable owner, not a rewritten paragraph.
+6. If review exposes an unwritten rejection rule, record it once in the
+   canonical review or engineering-rules surface.
+7. Do not create ADRs, changelog entries, roadmaps, generators, bots, or
+   docs-only gates unless the user or repository contract explicitly requires
+   that operating surface.
+
+## Repository-Specific Authority
+
+Do not impose stable filenames across projects. Discover authority from
+repository instructions, the root README, and existing docs navigation. Choose
+the smallest set of real information boundaries.
+
+When the repository designates them:
+
+- the root collaborator guide owns safety-critical invariants and navigation;
+- a reviewer playbook owns judgment calls, hard rejections, and historical
+  scars;
+- code standards own engineering choices, testing policy, naming, quality, and
+  contribution constraints;
+- system architecture owns current boundaries and a compact decision ledger;
+- a project overview owns product intent, non-goals, terminology, and business
+  constraints;
+- a codebase summary is navigation only, never per-file description;
+- operational guides own provider quirks and runbooks not expressible in code.
+
+Keep glossary and navigation separate and thin only when they are genuinely
+needed. Do not create placeholders to complete a template.
+
+## Sizing
+
+WHY docs are naturally short. A short honest navigation or rationale document
+is better than implementation paraphrase. Split only at real semantic
+boundaries and never pad.

package/skills/docs/references/documentation-management.md

@@ -0,0 +1,51 @@
+# Documentation Impact Routing
+
+Use this file when another workflow must decide whether docs are affected. For
+full operations, invoke `/pk:docs init`, `/pk:docs update`, `/pk:docs summarize`,
+or `/pk:docs agent-context` (root `CLAUDE.md`/`AGENTS.md`).
+
+## Update docs when a change affects
+
+- user-visible behavior, setup, commands, or configuration;
+- architecture, data flow, public contracts, security, or recovery;
+- machine-readable contracts or generated reference output;
+- an accepted maintainer decision that future work must not rediscover.
+
+Do not add documentation churn for internal edits whose observable contract did
+not change. Docs own WHY and WHERE; current WHAT and HOW must point to an
+executable owner. If a review exposes an unwritten rejection criterion, record
+it once in the repository's canonical review or standards surface.
+
+## Discover the target
+
+Read repository instructions, the root README, and the project's existing docs
+navigation. Search current docs for the changed concept. Do not route by a
+universal filename list.
+
+Update the smallest authority surface. If a command, inventory, matrix, or
+generated output already has a machine owner, update that owner and have prose
+link to it rather than copying the details.
+
+## Evidence and state
+
+- Evergreen docs describe durable intent and operating contracts.
+- Source, tests, manifests, generated output, artifacts, and live services prove
+  current behavior.
+- Plans, reports, audits, and release records are stateful evidence, not product
+  authority.
+
+Before updating a document, read it. After updating, verify links and claims
+against the owning evidence. Remove stale or duplicate text rather than adding
+another reconciliation layer.
+
+## Cross-skill handoffs
+
+- `/pk:cook` and `/pk:fix`: update docs during finalize only when the impact
+  criteria above apply.
+- The installed planning skill reads routed project context before creating an
+  execution plan.
+- `/pk:preview`: keep temporary visuals with the active plan; link them from
+  evergreen docs only when they remain useful.
+- `/pk:tech-graph`: use for publish-grade diagrams when a visual materially
+  improves the document.
+- Any skill editing `docs/` applies `references/doc-content-rules.md`.

package/skills/docs/references/init-workflow.md

@@ -0,0 +1,60 @@
+# Init Workflow
+
+Use this workflow to establish project documentation without imposing a
+template inherited from PrimeKit. Read `references/doc-content-rules.md` before
+authoring or delegating document changes. When the docs being authored include
+test-related guidance (how to set up, run, or structure tests), also load
+`references/practical-principles-for-setting-up-and-running-tests.md` and apply
+it; keep the result project-specific and evidence-backed.
+
+## 1. Brainstorm the docs contract
+
+Run the opening gate from the parent skill. Capture audience, intended
+decisions, authority, evidence, scope, and acceptance criteria.
+
+## 2. Inspect the project
+
+- Read repository instructions and the root README first.
+- Discover existing docs, plans, generated references, and navigation with
+  repository search tools.
+- Scout the relevant source and tests. Skip credentials, caches, dependencies,
+  generated bundles, and unrelated external trees.
+- Extract entry points, boundaries, decisions, alternatives, domain rules, and
+  cross-file constraints without copying mutable implementation details.
+- Identify which information is evergreen and which is a stateful record.
+
+## 3. Design the smallest useful route
+
+Choose files by information role, not by a preset filename list. A small
+project may need one routed document. A larger project may separate product
+intent, current decisions, workflow, architecture, machine contracts, and
+operations when those boundaries are real.
+
+- Reuse an existing route when it is coherent.
+- Add an index only when multiple documents need navigation.
+- Do not create empty placeholders, speculative roadmaps, or an ADR collection
+  merely to complete a template.
+- Keep machine-owned inventories in a manifest or generator output and link to
+  that owner from prose.
+
+Present the proposed route before writing when it would replace existing docs
+or materially change authority.
+
+## 4. Author with evidence
+
+Use `docs-manager` through the runtime's delegation capability when available;
+otherwise perform the same evidence-first work locally. Pass the brainstormed
+contract, discovered routes, evidence map, exact files to retain, replace, or
+remove, and relevant rules from `references/doc-content-rules.md`.
+
+If the project has little discoverable WHY, write short docs. Never pad with
+implementation paraphrases.
+
+## 5. Validate
+
+- Verify internal links and referenced paths.
+- Run examples or owning scripts where practical.
+- Confirm current claims against source, tests, artifacts, or live state.
+- Check that no fixed inventory or copied command sequence gained a second
+  maintenance owner.
+- Report created, changed, retained, and removed authority surfaces.

package/skills/docs/references/llms.md

@@ -0,0 +1,151 @@
+# llms.txt / llms-full.txt
+
+Generate or update **both** `llms.txt` and `llms-full.txt` for this project per
+the [llmstxt.org](https://llmstxt.org) specification. These files orient AI
+agents at inference time; they are not SEO, robots.txt, or crawl-control
+artifacts.
+
+## Goal
+
+Produce a curated machine-readable docs index (`llms.txt`) and a full-content
+companion (`llms-full.txt`) so agents can discover and load project
+documentation efficiently.
+
+## 1. Discover the source of truth
+
+1. Find the project's docs route via the Discovery Contract in the parent skill
+   (`AGENTS.md`/`CLAUDE.md`, root `README.md`, docs index/nav, then `docs/`).
+2. Treat the discovered docs route as source of truth — by convention `docs/`.
+3. Prefer stable public `.md` URL variants when the project serves a docs site
+   (e.g. `page.html.md` or `page.md`). Otherwise use repo-relative paths to the
+   markdown sources.
+4. Skip marketing copy, nav boilerplate, forums, ads, archived versions, and
+   duplicate pages. Keep citation-worthy current docs only.
+
+## 2. Choose the output location
+
+Write both files to:
+
+- the site's public/static directory when the project serves one
+  (e.g. `public/`, `static/`, framework `out/` / `dist/` when that is the
+  published root), otherwise
+- the repository root.
+
+Place `llms.txt` and `llms-full.txt` side by side in that location.
+
+## 3. Update in place (do not regenerate blindly)
+
+When either file already exists:
+
+1. Read the current file and the current docs tree.
+2. **Add** entries for new pages.
+3. **Drop** entries whose pages were deleted or relocated with no replacement.
+4. **Keep** curated section ordering and human-written notes unless evidence
+   shows they are wrong.
+5. Reconcile titles, URLs, and one-line notes against current docs.
+
+Only create from scratch when neither file exists.
+
+## 4. `llms.txt` grammar (exact)
+
+`llms.txt` is plain-text Markdown. Follow this ordered structure exactly:
+
+```markdown
+# Project Name
+
+> One-line summary of the project.
+
+Optional prose paragraphs or lists with key context.
+No headings allowed in this prose block.
+
+## Section Name
+
+- [Page title](url): one-line note
+- [Another page](url): one-line note
+
+## Optional
+
+- [Secondary page](url): one-line note
+```
+
+Rules:
+
+| Element | Requirement |
+|---|---|
+| H1 | **Required.** Exactly one `#` with the project/site name. |
+| Blockquote | One-line (or short) summary after the H1. Use `> …`. |
+| Optional prose | Zero or more paragraphs/lists **without any headings**. |
+| H2 sections | Group related links. Each item: `- [title](url): one-line note`. |
+| `## Optional` | Last H2. Agents may skip these entries when context is short. Put changelogs, legacy, and supplementary links here. |
+
+Hard constraints for `llms.txt`:
+
+- Links and one-line notes only — **never** inline page content.
+- Every note is a single concise line after `: `.
+- No duplicate URLs or titles across sections.
+- Keep the index small (typically tens of KB) so it fits agent context.
+
+## 5. `llms-full.txt` content
+
+`llms-full.txt` inlines the full documentation content in the same reading order
+as the curated sections in `llms.txt` (core sections first; optional last or
+omitted when size is a concern).
+
+For each page, include clean Markdown body (no HTML chrome, nav, or ads),
+preserve a clear heading hierarchy, and keep the canonical source URL
+discoverable (e.g. as a heading link).
+
+Size guidance (from llmstxt.org practice):
+
+| Size | Guidance |
+|---|---|
+| <200 KB | Comfortable for most agent queries |
+| 200 KB–1 MB | Prefer for focused/deep queries |
+| 1–2 MB | Near typical context limits; agents may chunk |
+| >2 MB | May exceed agent context — warn, trim non-essential pages, or expect fallback to `llms.txt` |
+
+Exclude changelogs, forums, and archived versions from the full file unless the
+user explicitly requests them. Prefer essential, citation-worthy content.
+
+## 6. Generation path
+
+When the engineer `pk:llms` skill and its `generate-llms-txt.py` script are
+installed in this environment, you MAY delegate generation to it:
+
+```bash
+# from the installed primekit-llms skill directory
+# index only
+../primekit-llms/scripts/generate-llms-txt.py --source <docs-route> --output <output-dir> [--base-url <url>]
+
+# index + full content
+../primekit-llms/scripts/generate-llms-txt.py --source <docs-route> --output <output-dir> --full [--base-url <url>]
+```
+
+After delegation: curate section order, one-line notes, the `## Optional` split,
+and drop noise the script included. Do not ship raw generator output unreviewed.
+
+Otherwise write both files manually from the discovered docs route, following
+sections 4–5.
+
+## 7. Validate before finishing
+
+Confirm all of the following:
+
+1. Both `llms.txt` and `llms-full.txt` exist at the chosen output location.
+2. `llms.txt` has the required H1, a blockquote summary, valid H2 link sections,
+   and `## Optional` last when secondary links exist.
+3. Every link resolves (public URL reachable, or repo-relative path exists).
+4. Every entry has a one-line note; no blank or multi-paragraph notes in
+   `llms.txt`.
+5. No duplicate entries (same URL or same title repeated).
+6. `llms.txt` contains no inlined page bodies.
+7. `llms-full.txt` reading order matches the curated index; note if the file is
+   large enough that agents may exceed context.
+
+Report output paths, entry counts, approximate `llms-full.txt` size, and any
+unresolved links or skipped pages.
+
+## Additional requests
+<additional_requests>
+  $ARGUMENTS
+</additional_requests>