docs(setup-docs): default to runtime deps with deny-list filter

[amondnet]

Summary

Rework the setup-docs skill around a narrow-by-default principle so that bootstrapping ASK on a project produces a focused AGENTS.md — curated libraries the AI will actually reference when writing application code — instead of 60 toolchain packages.

Problem

The previous skill told itself to parse dependencies + devDependencies + peerDependencies and fetch docs for every entry. In practice:

• AGENTS.md marker block gets flooded with linters (eslint*, @typescript-eslint/*), bundlers (vite, rollup*, tsup), test runners (vitest, @playwright/test), git hooks (husky, lint-staged), type shims (@types/*), and polyfills (core-js). These pollute the context AI agents load.
• Wall-clock time scales with the long tail of devDependencies.
• Failure rate is high — most of those packages don't have docs in the places the registry/sources look, so Step 5 reports a demoralizing pile of Failed entries.

Solution

1. Default scope: runtime dependencies only. Skip devDependencies / peerDependencies / dev-scoped equivalents in pypi, go, crates, pub, hex, maven. The scope table is spelled out in Step 1.
2. Deny-list filter. New references/deny-list.md catalogues glob patterns for noisy toolchain packages, grouped by category. The skill reads this file and drops matches before showing the user the plan.
3. Three-bucket confirmation. Step 2 now prints will fetch / skipped by deny-list / skipped devDependencies so the user sees exactly what was dropped.
4. Explicit overrides. Every exclusion is recoverable:
   • include-dev — add devDependencies (still filtered by deny-list)
   • include <names> — force-include specific packages
   • all — disable deny-list AND include dev/peer deps
5. No code changes. Pure skill/reference update. The CLI pipeline is unchanged.

Why a deny-list file (and not registry tags)?

I checked — the registry already supports tags in the schema, but existing entries only carry domain tags (framework, ai, validation). There's no build-tool / linter exclusion category yet, and most denied packages aren't in the registry at all. A hardcoded pattern list under references/deny-list.md is the lower-friction starting point; once we have enough data we can migrate to registry-driven exclusion without touching the skill again (the skill already says "read this file").

Test plan

• SKILL.md stays under the 500 LOC budget (200 LOC).
• references/deny-list.md explains matching rules, lists categories alphabetically within each section, and documents the user-override escape hatch.
• No code changes → no build/test impact.
• Manual verification on a real project in a follow-up — bootstrap ASK on a Nuxt app and confirm the bucket output looks right before merge.

---

Summary by cubic

Default setup-docs to runtime dependencies and add a deny-list so AGENTS.md lists libraries used at runtime, not toolchain packages. Clarifies peer dependency handling and override rules to make the plan explicit and predictable.

• New Features
  • Default scope: runtime dependencies only across npm, PyPI, Go (direct require entries, skip // indirect), Crates, Pub, Hex, and Maven.
  • Deny-list via skills/setup-docs/references/deny-list.md (glob patterns for eslint*, vite, jest, @types/*, husky, core-js, etc.).
  • Confirmation buckets: “will fetch”, “skipped by deny-list”, “skipped devDependencies”, and “skipped peerDependencies”.
  • Overrides: include-dev now also pulls in peerDependencies; include <name> force-includes from any soft-skip bucket (deny-list, dev, peer) but not workspace/path deps; all disables the deny-list and includes dev + peer deps.

^{Written for commit 4a8c78d. Summary will update on new commits.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	4a8c78d
Status:	✅  Deploy successful!
Preview URL:	https://4279cb89.ask-registry.pages.dev
Branch Preview URL:	https://docs-setup-docs-primary-deps.ask-registry.pages.dev

View logs

[cubic-dev-ai]

2 issues found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/setup-docs/references/deny-list.md">

<violation number="1" location="skills/setup-docs/references/deny-list.md:17">
P2: The `all` override is documented incorrectly here; it also includes dev/peer dependencies, not just disabling the deny-list. Otherwise users can trigger a much larger fetch set than this reference promises.</violation>
</file>

<file name="skills/setup-docs/SKILL.md">

<violation number="1" location="skills/setup-docs/SKILL.md:130">
P2: Peer dependencies are skipped silently here—the confirmation buckets only show `devDependencies`, so users cannot see npm peers that were excluded by default.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant U as User
    participant S as Setup-Docs Skill
    participant FS as Local Files (Manifests/Lockfiles)
    participant DL as NEW: Deny-List Reference
    participant AD as Add-Docs Pipeline

    Note over S,FS: Step 1: Dependency Discovery
    U->>S: Run setup-docs
    S->>FS: Parse manifest (e.g., package.json, go.mod)
    S->>FS: Parse lockfile (e.g., package-lock.json, go.sum)
    FS-->>S: Raw dependency list (name, version, scope)

    Note over S,DL: Step 1.5: Filtering & Bucketing
    S->>S: CHANGED: Apply default scope (runtime deps only)
    S->>DL: NEW: Read patterns from references/deny-list.md
    DL-->>S: Glob patterns (e.g., eslint*, @types/*)
    S->>S: NEW: Filter runtime deps against deny-list

    Note over U,S: Step 2: Three-Bucket Confirmation
    S->>U: CHANGED: Display buckets (Will fetch / Deny-listed / Skipped devDeps)
    
    alt User requests override (e.g., include-dev, include <name>, all)
        U->>S: Input override command
        S->>S: NEW: Recalculate buckets based on instruction
        S->>U: Show updated plan
    end

    U->>S: Confirm (yes)

    Note over S,AD: Step 3: Execution
    loop For each package in "Will fetch" bucket
        S->>AD: Invoke add-docs (Steps 1-6.5)
        AD-->>S: Documentation metadata & ask.lock update
    end

    S->>FS: Final pass: Rebuild AGENTS.md block
    S-->>U: Setup complete (Focused AGENTS.md generated)

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/setup-docs/SKILL.md">

<violation number="1" location="skills/setup-docs/SKILL.md:113">
P2: `include <name>` is documented as overriding every exclusion reason, but Step 1 still has non-overridable path/workspace skips. Limit this escape hatch to the deny-list and dev-dependency buckets only.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

_{Auto-approved: The changes are limited to AI skill instructions (Markdown) and a reference deny-list. There are no changes to core application code, and the risk to production systems is zero.}