docs: complete MAP MVP release readiness

.github/workflows/ci.yml

@@ -39,6 +39,10 @@ jobs:
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test
+      - name: Check the bundled registry snapshot
+        env:
+          MAP_REPO: ${{ github.workspace }}
+        run: node packages/cli/scripts/sync-snapshot.ts --check
       - name: Test the GitHub installer
         working-directory: .
         run: |

CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## Unreleased — architecture-layer MVP
+
+### Added
+
+- Product, system, pattern graph, scanner, recommendation, verification, CLI, MCP, and
+  security architecture documentation.
+- AI-focused ADRs for the deterministic core, stable pattern identity, versioned CLI
+  JSON, static analysis, and MCP isolation.
+- Pattern Schema v1 plus scan and recommendation result schemas with fixtures.
+- `map list`, `search`, `show`, `scan`, `suggest`, `graph`, and `validate`.
+- Evidence certainty and explicit static-analysis limitations.
+- Registry snapshot freshness enforcement in CI.
+
+### Changed
+
+- The YAML reader now supports folded and literal block strings used by pattern
+  metadata.
+- README and library documentation now use the GitHub-only installation path and
+  consolidated monorepo structure.
+- Saved analysis reports use the versioned scan-result envelope.
+
+### Compatibility
+
+- `map patterns`, `explain`, `analyze`, and `recommend` remain supported.
+- Pattern IDs remain `category/slug` for schema version 1.
+- Existing flat `related` metadata remains valid and maps to `works_with` graph edges.
+
+Earlier CLI changes are recorded in [`tooling/CHANGELOG.md`](tooling/CHANGELOG.md).

README.md

@@ -72,8 +72,9 @@ git pull --ff-only
 ```bash
 cd your-project
 map init
-map analyze
-map recommend
+map scan --json
+map suggest
+map search retrieval
 map optimize --save
 map sync
 ```
@@ -98,9 +99,9 @@ existing files:
 ## One workflow, every agent
 
 ```text
-project code ──▶ map analyze ──▶ detected AI architecture
+project code ──▶ map scan ────▶ detected AI architecture
                                       │
-MAP library ──▶ map recommend ──▶ missing patterns
+MAP library ──▶ map suggest ──▶ patterns to review
                                       │
                               map add / edit .map/
                                       │
@@ -114,14 +115,21 @@ MAP library ──▶ map recommend ──▶ missing patterns
 | Command | Result |
 |---|---|
 | `map init` | Creates the `.map/` workspace and detects the project shape. |
-| `map analyze` | Finds AI-related dependencies and architecture signals. |
-| `map recommend` | Suggests missing patterns with evidence and priority. |
-| `map patterns [query]` | Searches the local pattern catalog. |
+| `map scan [path] [--json]` | Finds static AI architecture signals, evidence, certainty, and limits. |
+| `map suggest [path] [--json]` | Suggests review candidates with triggers, rationale, and priority. |
+| `map list [--json]` | Lists the local pattern catalog. |
+| `map search [query] [--json]` | Searches patterns by ID, name, or summary. |
+| `map show <pattern-id> [--json]` | Shows one pattern and its decision guidance. |
+| `map graph [pattern-id] [--json]` | Inspects the catalog as typed relationships. |
 | `map add <pattern-id>` | Adds a pattern prompt, metadata, and acceptance criteria. |
+| `map validate [--json]` | Validates the project manifest and adopted pattern integrity. |
 | `map optimize --check` | Measures context and enforces the configured token budget. |
 | `map sync` | Generates instructions for supported AI coding assistants. |
 | `map doctor` | Checks the workspace, registry, compiler, and references. |
 
+The original `analyze`, `recommend`, `patterns`, and `explain` commands remain
+supported as compatible names.
+
 ## What is inside this repository?
 
 | Area | Purpose |
@@ -140,6 +148,9 @@ and verifiable acceptance criteria.
 
 - [Getting started](docs/getting-started.md)
 - [Project structure](docs/project-structure.md)
+- [Product vision and MVP](docs/project/VISION.md)
+- [System architecture](docs/architecture/README.md)
+- [Machine-readable specifications](docs/specifications/)
 - [Pattern library](library/README.md)
 - [Human- and AI-readable schemas](library/docs/schemas/README.md)
 - [MAP Standard RFC](library/rfcs/0001-map-standard.md)

docs/README.md

@@ -0,0 +1,16 @@
+# MAP documentation
+
+## Start here
+
+- [Getting started](getting-started.md)
+- [Project structure](project-structure.md)
+- [Vision](project/VISION.md), [product specification](project/PRODUCT_SPEC.md), and
+  [MVP scope](project/MVP.md)
+- [Architecture overview](architecture/README.md)
+- [Machine-readable specifications](specifications/)
+- [Phase 0 repository audit](project/CURRENT_STATE.md)
+- [MVP implementation report](project/MVP_IMPLEMENTATION_REPORT.md)
+
+Reusable AI engineering content lives in the [pattern library](../library/README.md).
+Architecture decisions for MAP itself live in [`.map/decisions`](../.map/decisions/).
+

docs/examples/map-self-scan.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "kind": "map.scan-result",
+  "root": "/workspace/map/tooling",
+  "detectedAt": "2026-09-13T13:08:19.022Z",
+  "analyzers": ["dependency-manifest"],
+  "inspected": ["package.json"],
+  "concepts": [],
+  "limitations": [
+    "Dependency manifests indicate declared packages, not whether or how code uses them.",
+    "The MVP scanner does not inspect source code, runtime behavior, nested workspaces, or secret values."
+  ]
+}

docs/getting-started.md

@@ -30,19 +30,22 @@ existing files unless `--force` is explicitly supplied.
 ## 3. Understand the architecture
 
 ```bash
-map analyze
-map recommend
-map patterns retrieval
+map scan
+map suggest
+map search retrieval
 ```
 
-`analyze` detects architecture signals from project manifests. `recommend`
-maps those signals to production patterns, and `patterns` lets you browse the
-full library.
+`scan` detects evidence-backed architecture signals from project manifests and states
+the limits of static analysis. `suggest` maps those signals to review candidates with
+reasons, and `search` lets you browse the full library. Add `--json` to consume stable
+scan and recommendation contracts from scripts or agents. The older `analyze`,
+`recommend`, and `patterns` names remain supported.
 
 ## 4. Adopt knowledge into the project
 
 ```bash
 map add retrieval/chunking
+map validate
 ```
 
 The pattern's prompt, acceptance criteria, and metadata are copied into

docs/project/MVP_IMPLEMENTATION_REPORT.md

@@ -0,0 +1,107 @@
+# MVP implementation report
+
+Status date: 2026-09-13  
+Tracking issue: [#103](https://github.com/rajanbor/map/issues/103)
+
+## Outcome
+
+MAP now has a documented and working deterministic architecture-layer MVP. It keeps
+the existing pattern catalog and `.map/` context compiler, adds enforced public
+contracts, exposes a queryable pattern graph, and completes a local workflow from
+discovery through structural validation.
+
+The implementation was delivered as reviewable stages:
+
+- [#104](https://github.com/rajanbor/map/pull/104): repository audit and baseline;
+- [#105](https://github.com/rajanbor/map/pull/105): product, architecture,
+  specifications, security model, and ADRs;
+- [#106](https://github.com/rajanbor/map/pull/106): Pattern Schema v1;
+- [#107](https://github.com/rajanbor/map/pull/107): deterministic CLI MVP and result
+  schemas.
+
+## Implemented
+
+### Contracts
+
+- Six offline-validated JSON Schema contracts: document, project, decision, pattern,
+  scan result, and recommendation result.
+- Pattern and anti-pattern base model with stable slash IDs, lifecycle, evidence,
+  MAP Score, legacy relations, and six typed relation kinds.
+- Complete valid fixtures and at least three invalid fixtures per schema.
+- Repository validation for every published `pattern.yaml`, directory identity,
+  required files, duplicate IDs, and relationship targets.
+
+### CLI and core
+
+- `list`, `search`, and `show`, with JSON discovery output.
+- `scan` with evidence, confidence, certainty, inspected inputs, analyzers, and limits.
+- `suggest` with deterministic priorities, triggers, and rationales.
+- `graph` over 96 catalog nodes and 37 normalized typed edges.
+- `validate` for `.map/map.config.json` and adopted-pattern file integrity.
+- Backward-compatible `patterns`, `explain`, `analyze`, and `recommend` commands.
+- Existing `init`, `add`, `sync`, `watch`, `optimize`, `doctor`, and `update` behavior
+  retained.
+
+### Operations
+
+- GitHub-only installer remains the documented distribution path.
+- Bundled registry snapshot refreshed from the consolidated monorepo.
+- CI now fails when the snapshot content differs from the registry built from source.
+- README and library entry points describe the actual monorepo and install path.
+
+## Dogfood result
+
+The built CLI was run against MAP itself:
+
+```text
+map scan tooling --json       valid map.scan-result
+map suggest tooling --json    valid map.recommendation-result
+map graph retrieval/chunking --json
+                              1 selected node, 6 outgoing works_with edges
+map validate --json           valid; .map/map.config.json checked
+```
+
+The retained [self-scan example](../examples/map-self-scan.json) sanitizes the local
+path. It contains no detections because the selected root `tooling/package.json` has no
+AI runtime dependency. Crucially, it reports that nested workspaces and source code
+were not inspected; the result is limited evidence, not a claim that MAP contains no
+AI-related architecture.
+
+## Verification evidence
+
+```text
+registry builder:  96 patterns, pass
+schema validator:   6 contracts, pass
+build:               pass
+lint:                pass
+typecheck:           pass
+tests:             146 pass (130 CLI, 13 score, 3 registry)
+pnpm audit:           no known vulnerabilities
+installer smoke:     pass in required CI job
+CLI JSON smoke:      scan, suggest, graph, validate pass
+```
+
+## Known limits
+
+- The scanner reads supported manifests only at the selected root. It does not yet
+  traverse monorepos or parse source and runtime behavior.
+- Current pattern metadata uses legacy `related` lists. The graph deliberately
+  normalizes these to `works_with`; stronger relation semantics require author review.
+- The rule-based recommender uses detected concepts, not declared project intent or
+  verified adopted-pattern state.
+- `validate` proves contract and file integrity, not pattern implementation.
+- Anti-patterns can be modeled and validated, but none is published in the catalog yet.
+- MCP, architecture diff, semantic indexing, and LLM-assisted analysis are deferred
+  adapters.
+- The npm package is not published; installation is from GitHub.
+
+## Recommended next increments
+
+1. Add bounded monorepo discovery with include/exclude rules and evidence de-duplication.
+2. Migrate reviewed pattern relations from legacy lists to explicit typed claims.
+3. Define adopted intent and verification checks before graph-backed recommendation
+   ranking.
+4. Publish the first anti-pattern with evidence and a `solves` relation.
+5. Align library and SDK version streams before promising npm distribution.
+6. Implement a read-only MCP adapter only after the core API contract is stable.
+

docs/project/ROADMAP.md

@@ -19,15 +19,19 @@ This roadmap describes capabilities. The pattern publication backlog remains in
 
 ## 2 — Evidence and verification
 
-- Add recursive workspace discovery and configurable source analyzers.
-- Model declared project intent and adopted-pattern verification.
+- Add recursive workspace discovery and configurable source analyzers
+  ([#108](https://github.com/rajanbor/map/issues/108)).
+- Model declared project intent and adopted-pattern verification
+  ([#110](https://github.com/rajanbor/map/issues/110)).
 - Add architecture diff, verification reports, and CI policy levels.
-- Expand evidence provenance and pattern lifecycle governance.
+- Expand evidence provenance, typed relations, graph-backed explanations, and pattern
+  lifecycle governance ([#109](https://github.com/rajanbor/map/issues/109)).
 
 ## 3 — Ecosystem adapters
 
 - Publish a protocol-neutral core API.
-- Add an MCP adapter as a separate package.
+- Add a read-only MCP adapter as a separate package
+  ([#111](https://github.com/rajanbor/map/issues/111)).
 - Define safe adapter and plugin discovery without executing untrusted code.
 - Add framework mappings that never become the canonical pattern model.
 
@@ -40,3 +44,6 @@ This roadmap describes capabilities. The pattern publication backlog remains in
 Each phase must preserve deterministic offline behavior as the baseline and may add
 assisted behavior only as an explicit adapter.
 
+Release-stream alignment and optional npm preparation are tracked separately in
+[#112](https://github.com/rajanbor/map/issues/112); GitHub remains the supported
+installation path until that work is complete and publicly verified.

docs/specifications/README.md

@@ -0,0 +1,14 @@
+# Specifications
+
+These documents explain MAP's versioned machine contracts in human terms:
+
+- [Pattern specification](PATTERN_SPEC.md)
+- [Pattern Schema v1](PATTERN_SCHEMA.md)
+- [MAP project manifest](MAP_MANIFEST.md)
+- [Scan Result v1](SCAN_RESULT.md)
+- [Recommendation Result v1](RECOMMENDATION_RESULT.md)
+- [Verification Result design](VERIFICATION_RESULT.md)
+
+Normative JSON Schemas and fixtures live in [`library/schemas`](../../library/schemas/).
+Architecture rationale lives in [`docs/architecture`](../architecture/), and accepted
+decisions live in [`.map/decisions`](../../.map/decisions/).

library/LICENSING.md

@@ -6,7 +6,7 @@ MAP uses two licenses so it's easy to build on, while authorship stays credited.
 
 | What | License | You can | You must |
 |------|---------|---------|----------|
-| **Code** — `reference/`, `examples/`, `scripts/` (the CLI lives in [missing-ai-patterns/cli](https://github.com/rajanbor/map/tree/main/tooling)) | [MIT](LICENSE) | Use, copy, modify, fork, ship commercially | Keep the copyright notice |
+| **Code** — `reference/`, `examples/`, `scripts/`, and [`tooling/`](../tooling/) | [MIT](LICENSE) | Use, copy, modify, fork, ship commercially | Keep the copyright notice |
 | **Content** — `patterns/`, `docs/`, prose, diagrams | [CC BY 4.0](LICENSE-CONTENT) | Use, share, adapt, even commercially | **Give attribution** to MAP / the author |
 | **Name & brand** — "MAP", "Missing AI Patterns", logos | Reserved (not licensed) | — | Use a different name for forks |
 

library/README.md

@@ -113,8 +113,8 @@ map/
   .github/       Contributor experience: templates, labels, discussions, CI
 ```
 
-The **MAP CLI** lives in its own repository,
-[missing-ai-patterns/cli](https://github.com/rajanbor/map/tree/main/tooling). It consumes the
+The **MAP CLI** lives in this repository under
+[`tooling/`](../tooling/). It consumes the
 **registry** — the machine-readable catalog this repository publishes with every release
 (see the [registry spec](docs/specs/registry.md)).
 
@@ -168,13 +168,18 @@ and guardrails, so its decisions are consistent and reviewable. See the
 
 The [MAP CLI](https://github.com/rajanbor/map/tree/main/tooling) surfaces this directly:
 
+Install it from GitHub (the npm package is not published yet):
+
 ```bash
-npm install -g @missing-ai-patterns/cli
+git clone https://github.com/rajanbor/map.git
+cd map
+./scripts/install.sh
 
-map explain retrieval/chunking     # what the pattern is and when to use it
+map init
+map show retrieval/chunking        # what the pattern is and when to use it
 map add retrieval/chunking         # copy prompt.md + acceptance.md into your .map/ workspace
-map analyze                        # detect the AI architecture already in your project
-map recommend                      # which MAP patterns your architecture is missing
+map scan                           # detect evidence-backed architecture signals
+map suggest                        # review patterns your architecture may need
 ```
 
 ## Contributing

library/docs/README.md

@@ -14,12 +14,12 @@ Specifications (the contracts tools build on — see the
 - **[Pattern Contract](pattern-contract.md)** — the files every pattern ships and who consumes them.
 - **[MAP Score](specs/map-score.md)** — the five-dimension 1–5 star rating. *(implemented)*
 - **[Registry](specs/registry.md)** — the machine-readable catalog artifact published on each release. *(implemented)*
-- **[Pattern Schema](specs/pattern-schema.md)** — the formal, build-enforced schema for `pattern.yaml`. *(draft)*
+- **[Pattern Schema](specs/pattern-schema.md)** — the formal, build-enforced schema for `pattern.yaml`. *(implemented)*
 - **[Pattern Lifecycle](specs/pattern-lifecycle.md)** — claiming, maturity, deprecation, and renames. *(draft)*
 - **[Decision Guides](specs/decision-guides.md)** — cross-category "X or Y?" guides and their contract. *(draft)*
 - **[Website](specs/website.md)** — the ultra-simple registry-fed site. *(draft)*
 - **[MAP Schemas](schemas/README.md)** — machine contracts paired with human guides and fixtures.
 
 For the patterns themselves, see [`../patterns/`](../patterns/). To contribute, see
-[`../CONTRIBUTING.md`](../CONTRIBUTING.md). The `map` CLI lives in
-[missing-ai-patterns/cli](https://github.com/rajanbor/map/tree/main/tooling).
+[`../CONTRIBUTING.md`](../CONTRIBUTING.md). The `map` CLI lives in this monorepo under
+[`../../tooling`](../../tooling/).