Refresh README and add GitHub-only installation

.github/workflows/ci.yml

@@ -39,6 +39,11 @@ jobs:
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test
+      - name: Test the GitHub installer
+        working-directory: .
+        run: |
+          MAP_INSTALL_DIR="$RUNNER_TEMP/map-bin" ./scripts/install.sh
+          "$RUNNER_TEMP/map-bin/map" --version
       - name: Smoke-test the built CLI
         run: |
           node packages/cli/dist/map.js --help

README.md

@@ -1,60 +1,166 @@
-# MAP — your AI engineering library
+<p align="center">
+  <img src="library/assets/map-logo.png" alt="MAP logo" width="180" />
+</p>
 
-MAP is a project toolkit for building AI systems with a repeatable structure.
-Initialize it inside an application, keep architecture knowledge in `.map/`, and
-use the CLI to analyze the codebase, adopt proven patterns, compile instructions
-for AI coding assistants, and keep context within a token budget.
+<h1 align="center">MAP — your AI engineering library</h1>
+
+<p align="center">
+  One project structure for architecture decisions, prompts, agents, evaluations,<br />
+  reusable AI patterns, and context optimization.
+</p>
+
+<p align="center">
+  <a href="https://github.com/rajanbor/map/actions/workflows/ci.yml"><img src="https://github.com/rajanbor/map/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="library/LICENSE"><img src="https://img.shields.io/badge/code-MIT-2ea44f" alt="Code license: MIT" /></a>
+  <a href="library/LICENSE-CONTENT"><img src="https://img.shields.io/badge/content-CC_BY_4.0-blue" alt="Content license: CC BY 4.0" /></a>
+  <img src="https://img.shields.io/badge/Node.js-%E2%89%A520-43853d" alt="Node.js 20 or newer" />
+</p>
+
+MAP helps a software project explain itself to people and AI coding agents. You keep
+the durable knowledge in one `.map/` directory. The CLI can analyze the project,
+recommend missing production patterns, control the context budget, and generate the
+native instruction files used by different assistants.
+
+> **Current distribution:** MAP is installed directly from this GitHub repository.
+> The npm package is not published yet, so do not use `npm install
+> @missing-ai-patterns/cli`.
+
+## Why MAP?
+
+AI projects quickly scatter important knowledge across prompts, chat histories,
+vendor configuration, diagrams, and developer notes. That makes agents repeat old
+mistakes and makes architectural decisions difficult to review.
+
+MAP gives that knowledge a stable home:
+
+- **one source of truth** for every supported coding assistant;
+- **reusable patterns** with trade-offs, implementation prompts, and acceptance tests;
+- **AI-aware ADRs and schemas** readable by people and machines;
+- **token-budget control** that exposes oversized and duplicated context;
+- **Git-native collaboration** with deterministic, reviewable changes and offline operation.
+
+## Install from GitHub
+
+Requirements: Git, Node.js 20 or newer, and either `pnpm` or `corepack`.
+
+```bash
+git clone https://github.com/rajanbor/map.git
+cd map
+./scripts/install.sh
+map --version
+```
+
+The installer builds the CLI from this checkout and creates a `map` symlink in
+`~/.local/bin`. It never overwrites an unrelated executable. To choose another
+location:
+
+```bash
+MAP_INSTALL_DIR="$HOME/bin" ./scripts/install.sh
+```
+
+If that directory is not in `PATH`, the installer prints the exact line to add to
+your shell configuration. To update MAP later:
 
 ```bash
-npm install -g @missing-ai-patterns/cli
-cd my-ai-project
+cd map
+git pull --ff-only
+./scripts/install.sh
+```
+
+## Start an AI project
+
+```bash
+cd your-project
 map init
 map analyze
 map recommend
 map optimize --save
 map sync
 ```
 
-`map init` creates a concrete, versioned workspace:
+`map init` detects the project and creates a versioned workspace without overwriting
+existing files:
 
 ```text
 .map/
-├── map.config.json     project, analyzers, context targets, and tool settings
-├── architecture/      system boundaries, data flow, and diagrams
+├── map.config.json     project, analyzers, targets, and tool settings
+├── architecture/      system boundaries, data flows, and diagrams
 ├── decisions/         AI architecture decision records
 ├── patterns/          patterns adopted with `map add`
-├── prompts/           reusable project prompts
-├── agents/            agent roles and guardrails
-├── evals/             datasets, rubrics, and evaluation configuration
-├── tools/             project-level tool guidance and budgets
-├── reports/           generated analysis and token reports (gitignored)
-└── cache/             local registry/tool caches (gitignored)
+├── prompts/           reusable product and engineering prompts
+├── agents/            agent roles, permissions, and guardrails
+├── evals/             datasets, rubrics, metrics, and quality gates
+├── tools/             tool contracts and context budgets
+├── reports/           generated analysis reports; ignored by Git
+└── cache/             local registry cache; ignored by Git
 ```
 
-## Repository map
+## One workflow, every agent
+
+```text
+project code ──▶ map analyze ──▶ detected AI architecture
+                                      │
+MAP library ──▶ map recommend ──▶ missing patterns
+                                      │
+                              map add / edit .map/
+                                      │
+                                  map sync
+                                      │
+                 ┌────────────────────┼────────────────────┐
+                 ▼                    ▼                    ▼
+             AGENTS.md            CLAUDE.md        Cursor / Copilot / Gemini
+```
+
+| 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 add <pattern-id>` | Adds a pattern prompt, metadata, and acceptance criteria. |
+| `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. |
+
+## What is inside this repository?
 
 | Area | Purpose |
-| --- | --- |
-| [`library/`](library/) | The pattern library, specifications, examples, and reference implementations |
-| [`tooling/`](tooling/) | The MAP CLI and reusable TypeScript packages |
-| [`apps/website/`](apps/website/) | The public registry-driven website |
-| [`docs/`](docs/) | Product model, project structure, and getting-started guides |
-| [`.map/`](.map/) | MAP's own project workspace — MAP uses the structure it generates |
-
-## Core workflow
-
-1. `map init` detects the project and creates `.map/` without overwriting user files.
-2. `map analyze` identifies AI-related technologies and architecture signals.
-3. `map recommend` suggests missing production patterns.
-4. `map add <pattern-id>` adopts a pattern into the project workspace.
-5. `map optimize` estimates context usage, flags repeated content, and enforces a token budget.
-6. `map sync` compiles the same source of truth into `CLAUDE.md`, `AGENTS.md`,
-   `GEMINI.md`, Cursor rules, and Copilot instructions.
-
-Start with [Getting started](docs/getting-started.md), review the
-[project structure](docs/project-structure.md), or browse the
-[pattern catalog](library/README.md).
-
-The original MAP repositories were consolidated here with their Git histories,
-branches, tags, and releases preserved.
+|---|---|
+| [`library/`](library/) | AI engineering patterns, schemas, specifications, examples, and small reference implementations. |
+| [`tooling/`](tooling/) | The TypeScript CLI, context compiler, analyzers, recommender, and shared packages. |
+| [`apps/website/`](apps/website/) | The public, registry-driven pattern browser. |
+| [`docs/`](docs/) | Getting started, project structure, and product documentation. |
+| [`.map/`](.map/) | MAP's own workspace. The project uses the same structure it generates. |
+
+The pattern library is framework-agnostic. Each published pattern explains when to
+use it, when not to use it, its failure modes, trade-offs, an implementation prompt,
+and verifiable acceptance criteria.
+
+## Explore
+
+- [Getting started](docs/getting-started.md)
+- [Project structure](docs/project-structure.md)
+- [Pattern library](library/README.md)
+- [Human- and AI-readable schemas](library/docs/schemas/README.md)
+- [MAP Standard RFC](library/rfcs/0001-map-standard.md)
+- [Schema roadmap](https://github.com/rajanbor/map/issues/98)
+
+## Develop MAP
+
+```bash
+git clone https://github.com/rajanbor/map.git
+cd map/tooling
+corepack pnpm install --frozen-lockfile
+corepack pnpm test
+corepack pnpm build
+```
+
+Contributions should be small, testable, and readable by both people and agents. See
+the [contribution guide](library/CONTRIBUTING.md) and open roadmap issues before
+starting a larger contract change.
+
+## License
 
+Code is available under the [MIT License](library/LICENSE). Documentation, patterns,
+and other written content use [CC BY 4.0](library/LICENSE-CONTENT). The MAP name and
+logo remain reserved as described in [LICENSING.md](library/LICENSING.md).

docs/getting-started.md

@@ -3,18 +3,31 @@
 MAP turns project-specific AI knowledge into a small, versioned workspace that
 both people and coding agents can use.
 
-## 1. Initialize a project
+## 1. Install MAP from GitHub
+
+```bash
+git clone https://github.com/rajanbor/map.git
+cd map
+./scripts/install.sh
+map --version
+```
+
+MAP is currently distributed from its GitHub repository; the npm package is not
+published yet. The installer builds the CLI and links it into `~/.local/bin` without
+overwriting an unrelated executable. It requires Git, Node.js 20+, and `pnpm` or
+`corepack`.
+
+## 2. Initialize a project
 
 ```bash
-npm install -g @missing-ai-patterns/cli
 cd your-project
 map init
 ```
 
 The initializer detects known language markers and creates `.map/`. It keeps
 existing files unless `--force` is explicitly supplied.
 
-## 2. Understand the architecture
+## 3. Understand the architecture
 
 ```bash
 map analyze
@@ -26,7 +39,7 @@ map patterns retrieval
 maps those signals to production patterns, and `patterns` lets you browse the
 full library.
 
-## 3. Adopt knowledge into the project
+## 4. Adopt knowledge into the project
 
 ```bash
 map add retrieval/chunking
@@ -36,7 +49,7 @@ The pattern's prompt, acceptance criteria, and metadata are copied into
 `.map/patterns/`, where they can be adapted to the application and reviewed
 with the rest of the code.
 
-## 4. Keep context efficient
+## 5. Keep context efficient
 
 ```bash
 map optimize
@@ -49,7 +62,7 @@ shows the largest files, identifies substantial repeated blocks, and optionally
 enforces the budget in CI. The default budget and globs live under
 `tools.tokenOptimizer` in `.map/map.config.json`.
 
-## 5. Compile assistant instructions
+## 6. Compile assistant instructions
 
 ```bash
 map sync

scripts/install.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+map_repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+map_install_dir="${MAP_INSTALL_DIR:-${HOME}/.local/bin}"
+map_executable="${map_repo_root}/tooling/packages/cli/dist/map.js"
+map_link="${map_install_dir}/map"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "error: Node.js 20 or newer is required" >&2
+  exit 1
+fi
+
+map_node_major="$(node -p 'Number(process.versions.node.split(".")[0])')"
+if (( map_node_major < 20 )); then
+  echo "error: Node.js 20 or newer is required; found $(node --version)" >&2
+  exit 1
+fi
+
+if command -v pnpm >/dev/null 2>&1; then
+  map_package_manager=(pnpm)
+elif command -v corepack >/dev/null 2>&1; then
+  map_package_manager=(corepack pnpm)
+else
+  echo "error: pnpm or corepack is required to build MAP" >&2
+  exit 1
+fi
+
+mkdir -p "${map_install_dir}"
+if [[ -e "${map_link}" || -L "${map_link}" ]]; then
+  map_existing_target="$(readlink "${map_link}" 2>/dev/null || true)"
+  if [[ "${map_existing_target}" != "${map_executable}" ]]; then
+    echo "error: ${map_link} already exists and was not created by this checkout" >&2
+    echo "Choose another location with MAP_INSTALL_DIR=/path/to/bin." >&2
+    exit 1
+  fi
+fi
+
+echo "Building MAP from ${map_repo_root}"
+(
+  cd "${map_repo_root}/tooling"
+  "${map_package_manager[@]}" install --frozen-lockfile
+  "${map_package_manager[@]}" build
+)
+
+if [[ ! -L "${map_link}" ]]; then
+  ln -s "${map_executable}" "${map_link}"
+fi
+
+map_version="$("${map_link}" --version | tr -d '[:space:]')"
+echo "Installed MAP ${map_version} as ${map_link}"
+case ":${PATH}:" in
+  *":${map_install_dir}:"*) ;;
+  *)
+    echo "Add this directory to PATH:"
+    echo "  export PATH=\"${map_install_dir}:\$PATH\""
+    ;;
+esac

tooling/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@missing-ai-patterns/cli-workspace",
   "private": true,
+  "packageManager": "pnpm@10.11.0",
   "description": "Workspace for the MAP CLI and shared libraries.",
   "type": "module",
   "license": "MIT",

tooling/packages/cli/README.md

@@ -9,12 +9,18 @@ bundled with the package, so everything except `map update` works offline.
 
 ## Install
 
+The CLI is currently installed from the MAP GitHub repository. The npm package is
+not published yet.
+
 ```bash
-npm install -g @missing-ai-patterns/cli   # or pnpm add -g / npx
+git clone https://github.com/rajanbor/map.git
+cd map
+./scripts/install.sh
 map --help
 ```
 
-Requires Node >= 20.
+Requires Git, Node >= 20, and `pnpm` or `corepack`. The installer builds this checkout
+and links `map` into `~/.local/bin`; set `MAP_INSTALL_DIR` to choose another location.
 
 ## Commands