feat(cli): auto-manage ignore files for vendored .ask/docs

[amondnet]

Summary

Marks .ask/docs/ as vendored third-party documentation so that lint/format/code-review tools skip it, while keeping the directory readable as AI context.

Closes #24

Strategy

• (A) Self-contained nested configs inside .ask/docs/: .gitattributes, eslint.config.mjs, biome.json, .markdownlint-cli2.jsonc. Covers Git, ESLint flat config, Biome, and markdownlint-cli2 without touching root files (these tools all walk up from each file to find the nearest config).
• (B) Extend the existing AGENTS.md auto-generated block with a "Vendored Documentation" notice. CodeRabbit, cubic, Claude Code, Cursor rules, Codex, Copilot, Continue, and Aider all auto-consume this context file, so a single notice transitively affects every major AI review tool (verified against vendor docs).
• (C) Patch root files only for tools that do NOT support nested resolution: .prettierignore and sonar-project.properties get a marker block (# ask:start ... # ask:end). Legacy .markdownlintignore is patched with a warning to migrate to markdownlint-cli2. Files are only patched when they already exist — ASK never creates a root ignore file from scratch.

What's New

• packages/cli/src/markers.ts — pure inject / remove / wrap helpers for marker blocks (HTML and hash comment syntaxes)
• packages/cli/src/ignore-files.ts — categories A/C plus the manageIgnoreFiles orchestrator called from add / sync / remove
• ConfigSchema.manageIgnores — optional flag (default true); set to false in .ask/config.json to disable

Test plan

• bun --cwd packages/cli test — 199 pass, 0 fail (43 new tests added)
• bun --cwd packages/cli lint — clean
• Manual smoke: in a fresh project with a .prettierignore, run ask docs add npm:react, verify nested configs + AGENTS.md notice + .prettierignore patch
• Manual: ask docs remove react → verify all artifacts cleaned up
• Manual: git check-attr -a path/to/file/inside/.ask/docs/foo.md reports linguist-vendored true

Verification Checklist

(See `plan.md` ## Verification.)

• AC-1 — 4 nested files created
• AC-2 — AGENTS.md created with vendored notice when missing
• AC-3 — CLAUDE.md `@AGENTS.md` import (existing behaviour preserved)
• AC-4 — `.prettierignore` patched only when present
• AC-5 — Idempotent across repeat `add` invocations
• AC-6 — `remove` cleans all artifacts but preserves user files
• AC-7 — `manageIgnores: false` skips entirely
• AC-8 — Root `.gitattributes` untouched (nested attribute resolution verified)

---

Summary by cubic

Automatically marks .ask/docs/ as vendored and manages ignore configs so linters/formatters/review tools skip it, while keeping docs readable as context. Addresses #24.

• New Features

  • Adds manageIgnoreFiles to install/remove ignore artifacts during ask docs add|sync|remove.
  • Creates nested configs in .ask/docs/: .gitattributes, eslint.config.mjs, biome.json, .markdownlint-cli2.jsonc.
  • Extends AGENTS.md with a "Vendored Documentation" notice inside the auto-generated block.
  • Patches root files only if present: .prettierignore, sonar-project.properties, and legacy .markdownlintignore via # ask:start ... # ask:end blocks.
  • Adds manageIgnores (default true) to .ask/config.json to disable ignore management when needed.

• Bug Fixes

  • runSync now always runs manageIgnoreFiles, independent of --skip-agents-md, to keep tooling in sync with .ask/docs/.
  • manageIgnoreFiles no longer swallows corrupt .ask/config.json errors; they surface instead.

^{Written for commit 297c710. Summary will update on new commits.}

[codecov]

Codecov Report

❌ Patch coverage is 99.49495% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/cli/src/ignore-files.ts	99.31%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	297c710
Status:	⚡️  Build in progress...

View logs

[cubic-dev-ai]

2 issues found across 16 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="packages/cli/src/index.ts">

<violation number="1" location="packages/cli/src/index.ts:286">
P2: skipAgentsMd is documented to skip only AGENTS.md regeneration, but manageIgnoreFiles is now gated by the same flag, changing behavior and leaving ignore files unsynchronized when skipAgentsMd is true.</violation>
</file>

<file name="packages/cli/src/ignore-files.ts">

<violation number="1" location="packages/cli/src/ignore-files.ts:217">
P2: manageIgnoreFiles swallows all config load errors and still mutates ignore files, so invalid/unreadable config silently proceeds with changes instead of surfacing the error or skipping management.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant CLI as CLI Command (add/sync/remove)
    participant CFG as Config Loader
    participant AGM as Agents Generator
    participant IGN as NEW: IgnoreFiles Orchestrator
    participant MRK as NEW: Marker Helpers
    participant FS as File System

    Note over CLI,FS: Execution Flow for 'add' or 'sync'

    CLI->>CFG: loadConfig()
    CFG-->>CLI: config (inc. manageIgnores)

    CLI->>AGM: CHANGED: generateAgentsMd()
    AGM->>AGM: Prepend "Vendored Documentation" notice
    AGM->>FS: Update AGENTS.md with extended marker block
    
    opt manageIgnores is true (default)
        CLI->>IGN: NEW: manageIgnoreFiles(dir, 'install')
        
        Note over IGN,FS: Category A: Nested Configs
        IGN->>FS: NEW: Write .ask/docs/.gitattributes
        IGN->>FS: NEW: Write .ask/docs/eslint.config.mjs
        IGN->>FS: NEW: Write .ask/docs/biome.json
        IGN->>FS: NEW: Write .ask/docs/.markdownlint-cli2.jsonc

        Note over IGN,FS: Category C: Root Patching
        loop For each: .prettierignore, sonar-project.properties, .markdownlintignore
            IGN->>FS: Check if file exists
            alt File Exists
                FS-->>IGN: Existing content
                IGN->>MRK: NEW: wrap(payload, syntax)
                MRK-->>IGN: block
                IGN->>MRK: NEW: inject(content, block)
                MRK-->>IGN: updated content
                IGN->>FS: NEW: Write patched file
            end
        end
    end

    Note over CLI,FS: Execution Flow for 'remove' (last doc)

    CLI->>CLI: Check remaining docs
    opt No docs remaining
        CLI->>IGN: NEW: manageIgnoreFiles(dir, 'remove')
        IGN->>FS: NEW: Delete nested configs in .ask/docs/
        loop For each potential root patch
            IGN->>FS: Read file
            IGN->>MRK: NEW: remove(content, syntax)
            MRK-->>IGN: content without marker block
            IGN->>FS: NEW: Write cleaned root file
        end
    end

Loading

_{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 4 files (changes from recent commits).

_{Requires human review: This PR introduces automatic modification of project-level configuration files (e.g., .prettierignore) and new file creation, which requires human review of the architectural strategy.}