feat(cli): in-place npm docs — reference node_modules directly

[amondnet]

Summary

• When convention-based discovery finds docs shipped inside an npm package (e.g. node_modules/next/dist/docs/), ASK now references them in place instead of copying into .ask/docs/
• Adds --no-in-place CLI flag and ask.json inPlace field for opt-out (precedence: CLI > ask.json > default true)
• AGENTS.md differentiates in-place entries with "shipped by the package — bun install keeps them in sync" wording

Key changes

Layer	Files	What
Schema	ask-json.ts, resolved.ts	inPlace?: boolean, materialization, inPlacePath fields
Discovery	types.ts, local-conventions.ts, local-ask.ts	inPlace?: true marker on discovery results
Install	install.ts	materializeInPlace() — skip saveDocs, clean stale dirs, stamp resolved cache
Output	agents.ts, storage.ts	Differentiated AGENTS.md block + listDocs for in-place entries
CLI	index.ts	--no-in-place flag on install/add commands
Tests	2 new test files, 1 updated	SC-1 through SC-8 integration tests

Closes #56

Test plan

• bun run build — all packages compile
• bun run --cwd packages/schema test — 57 pass
• bun run --cwd packages/cli test — 240 pass (10 new)
• bun run --cwd packages/cli lint — clean
• Verify ask install on a project with npm:next (canary with dist/docs/) produces in-place AGENTS.md
• Verify ask install --no-in-place on the same project copies into .ask/docs/
• Verify ask remove npm:next on an in-place entry cleans resolved entry without touching node_modules/

---

Summary by cubic

ASK now references docs shipped inside npm packages directly from node_modules instead of copying to .ask/docs/, cutting disk use and staying in sync with your lockfile. Adds an opt‑out via --no-in-place and an ask.json inPlace field, and enforces schema validation for in‑place entries. Closes #56.

• New Features

  • In‑place discovery: when docs are under node_modules/<pkg>/<subdir>/, skip copy and record materialization: 'in-place' with inPlacePath.
  • CLI: --no-in-place on ask install and ask add to force copy.
  • Config: ask.json supports inPlace?: boolean (default true).
  • AGENTS.md: in‑place entries include “shipped by the package — bun install keeps them in sync”.
  • Cleanup: removes stale .ask/docs/<pkg>@*/ when switching from copy to in‑place.
  • Schema: require inPlacePath when materialization is 'in-place'.

• Migration

  • Default changes for convention‑detected npm docs: they’re referenced in place.
  • To force copy, run ask install --no-in-place or set "inPlace": false in ask.json (precedence: CLI > ask.json > default).

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

[cloudflare-workers-and-pages]

Deploying ask-registry with    Cloudflare Pages

Latest commit:	da010cd
Status:	🚫  Build failed.

View logs

[codecov]

Codecov Report

❌ Patch coverage is 96.26168% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
packages/cli/src/install.ts	95.06%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

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

_{Requires human review: This PR introduces a significant architectural change in how documentation is stored and referenced (in-place node_modules), modifying core installation and discovery logic.}

[cubic-dev-ai]

1 issue found across 18 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/schema/src/resolved.ts">

<violation number="1" location="packages/schema/src/resolved.ts:32">
P2: Enforce the schema invariant that `inPlacePath` is required when `materialization` is `'in-place'` to avoid accepting inconsistent resolved entries.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as CLI User
    participant CLI as CLI Command (index.ts)
    participant Install as Install Service (install.ts)
    participant Discovery as Local Discovery
    participant NPM as node_modules
    participant AskStorage as .ask/docs/ (Vendored)
    participant ResolvedStore as resolved.json (Cache)
    participant AgentsMD as AGENTS.md

    User->>CLI: ask install [--no-in-place]
    
    CLI->>Install: runInstall(options)
    Note over CLI,Install: NEW: Resolve inPlace priority:<br/>CLI flag > ask.json > default(true)

    loop Each Library
        Install->>Discovery: runLocalDiscovery()
        Discovery->>NPM: Check conventions (dist/docs, etc.)
        
        alt NEW: In-place allowed AND docs found in node_modules
            NPM-->>Discovery: Found docs path
            Discovery-->>Install: DocsDiscoveryResult (inPlace: true)
            
            Install->>Install: NEW: materializeInPlace()
            Install->>AskStorage: NEW: removeDocs() (Clean up any stale copies)
            
            opt Force or Version Mismatch
                Install->>ResolvedStore: NEW: Update entry (materialization: 'in-place', inPlacePath)
            end
            
        else Standard Copy Path (Opt-out or Not Found)
            Discovery-->>Install: Not found or disabled
            Install->>Install: materialize (Copy pipeline)
            Install->>AskStorage: saveDocs() (Download/Copy to .ask/docs/)
            Install->>ResolvedStore: Update entry (materialization: 'copy')
        end
    end

    Install->>AgentsMD: generateAgentsMd()
    AgentsMD->>ResolvedStore: Read materialization metadata
    
    alt CHANGED: Entry is 'in-place'
        AgentsMD->>AgentsMD: Emit "shipped by package" block<br/>pointing to node_modules
    else Entry is 'copy'
        AgentsMD->>AgentsMD: Emit standard block<br/>pointing to .ask/docs/
    end

    Install-->>User: Install Summary

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

_{Requires human review: Significant feature change modifying core installation logic and default storage behavior. Changes the materialization strategy for npm docs and touches critical paths in the CLI.}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Requires human review: Significant changes to core installation logic, file system management, and configuration schema. Requires human verification of the in-place referencing strategy.}