@jstn-sdk/ma 0.1.12 → 0.14.0

package/README.md

@@ -1,13 +1,12 @@
 <div align="center">
-  <img src="./docs/assets/meta-architect-logo.svg" alt="Meta-Architect logo" width="1024" height="240">
-  <p>Production-grade Codex skills and plugin package for architecture, evidence-backed OSS selection, gate-driven review, and release-minded build guidance.</p>
+  <img src="https://raw.githubusercontent.com/JustineDevs/meta-architect/v0.14.0/docs/assets/meta-architect-logo.svg" alt="Meta-Architect: quality gates and evidence verification for AI coding agents" width="1024" height="240">
+  <h1>Meta-Architect</h1>
+  <p><strong>Quality gates and evidence verification for AI coding agents.</strong></p>
+  <p>Your agent writes code fast. Meta-Architect makes it prove each stage first. Design, evidence, logic, security, experience, build. Each gate stays locked until the one before it passes.</p>
   <p>
+    <img src="https://img.shields.io/github/v/release/JustineDevs/meta-architect?display_name=tag&sort=semver" alt="GitHub release">
     <img src="https://img.shields.io/npm/v/%40jstn-sdk%2Fma" alt="npm version">
-    <img src="https://img.shields.io/badge/node-%3E%3D20-339933" alt="Node.js 20+">
-    <img src="https://img.shields.io/github/v/release/JustineDevs/meta-architect" alt="GitHub release">
-    <img src="https://img.shields.io/badge/license-MIT-16A34A" alt="MIT License">
-  </p>
-  <p>
+    <img src="https://img.shields.io/npm/dm/%40jstn-sdk%2Fma" alt="npm downloads">
     <a href="https://www.buymeacoffee.com/justinedevs">
       <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ffdd00?style=flat-square&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee">
     </a>
@@ -15,716 +14,193 @@
       <img src="https://img.shields.io/badge/GitHub%20Sponsors-JustineDevs-1f6feb?style=flat-square&logo=githubsponsors&logoColor=white" alt="GitHub Sponsors">
     </a>
   </p>
+  <p><a href="#quick-start">Quick Start</a> · <a href="./DEMO.md">Demo</a> · <a href="./COVERAGE.md">Verified Coverage</a> · <a href="#how-do-i-contribute">Contributing</a> · <a href="https://github.com/JustineDevs/meta-architect/issues">Issues</a></p>
 </div>
 
-> [!IMPORTANT]
-> Meta-Architect `v0.1.12` is a production-grade skills line.
-> It is not a lightweight demo branch.
-> From `v0.1.12` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
-
-## Overview
-
-Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution.
-
-It adds:
-
-- an architecture-first lane before implementation
-- evidence-backed OSS selection through GitMCP-connected sources
-- explicit logic, security, and DX/UX review gates
-- a singular `$maestro` bounded autonomous manager plus non-gating helper skills for alignment, diagnosis, test-first work, and cleanup
-- installable skills and a reproducible package surface
-
 > [!NOTE]
+> Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution.
 > Meta-Architect does not replace your coding runtime.
 > It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.
 
-## Support
-
-- [GitHub Sponsors](https://github.com/sponsors/JustineDevs)
-- [Buy Me A Coffee](https://www.buymeacoffee.com/justinedevs)
-
-<table>
-  <tr>
-    <td><strong>Linux-native packages</strong></td>
-    <td><code>.deb</code> for Debian-family distros, <code>.pkg.tar.xz</code> for Arch-family distros, and <code>.rpm</code> for Fedora/openSUSE-style distros</td>
-  </tr>
-  <tr>
-    <td><strong>npm package</strong></td>
-    <td><code>@jstn-sdk/ma</code> (fallback install path)</td>
-  </tr>
-  <tr>
-    <td><strong>Helper command</strong></td>
-    <td><code>ma</code> (secondary support surface)</td>
-  </tr>
-  <tr>
-    <td><strong>Runtime</strong></td>
-    <td>Node.js <code>&gt;=20</code>, npm <code>@10</code></td>
-  </tr>
-  <tr>
-    <td><strong>Release line</strong></td>
-    <td><code>v0.1.12</code></td>
-  </tr>
-  <tr>
-    <td><strong>License</strong></td>
-    <td><a href="./LICENSE">MIT</a></td>
-  </tr>
-</table>
-
-## Screenshots
-
-<table>
-  <tr>
-    <td><img src="./docs/assets/image/Screenshot(1).png" alt="Meta-Architect screenshot 1" width="280"></td>
-    <td><img src="./docs/assets/image/Screenshot(2).png" alt="Meta-Architect screenshot 2" width="280"></td>
-    <td><img src="./docs/assets/image/Screenshot(3).png" alt="Meta-Architect screenshot 3" width="280"></td>
-  </tr>
-  <tr>
-    <td><img src="./docs/assets/image/Screenshot(4).png" alt="Meta-Architect screenshot 4" width="280"></td>
-    <td><img src="./docs/assets/image/Screenshot(5).png" alt="Meta-Architect screenshot 5" width="280"></td>
-    <td><img src="./docs/assets/image/Screenshot(6).png" alt="Meta-Architect screenshot 6" width="280"></td>
-  </tr>
-  <tr>
-    <td><img src="./docs/assets/image/Screenshot(7).png" alt="Meta-Architect screenshot 7" width="280"></td>
-    <td><img src="./docs/assets/image/Screenshot(8).png" alt="Meta-Architect screenshot 8" width="280"></td>
-    <td><img src="./docs/assets/image/Screenshot(9).png" alt="Meta-Architect screenshot 9" width="280"></td>
-  </tr>
-</table>
-
-## Prerequisites
-
-- Node.js `>=20`
-- npm `>=10`
-- Git
-- an MCP-capable coding runtime
-- Codex for the recommended package-first path
-- macOS, Linux, or WSL2 recommended
-
-> [!TIP]
-> The most reliable default environment is a Unix-like shell with Git, Node.js, and an MCP-capable runtime already configured.
-
-## Default Install Surfaces
-
-Meta-Architect is a Codex-native session workflow. On Linux, the primary install surface is now distro-style package installation, not a standalone binary shell.
-
-### Debian, Ubuntu, Linux Mint, Pop!_OS
-
-Download the GitHub release `.deb` asset and install it with your normal package command:
-
-```bash
-sudo apt install ./meta-architect_<version>_all.deb
-```
+<img src="https://raw.githubusercontent.com/JustineDevs/meta-architect/v0.14.0/docs/assets/DEMO_VIDEO.gif" alt="Meta-Architect demo video" width="800">
 
-### Arch, Manjaro, EndeavourOS
+<details>
+<summary><strong>🔌 All 33 plugins & features</strong></summary>
 
-Download the GitHub release pacman package asset and install it with:
+The plugin and feature inventory is maintained in the [support bundle manifest](./support-bundle.json) and [skills manifest](./skills/index.json), with verification in the [coverage documentation](./COVERAGE.md).
+</details>
 
-```bash
-sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
-```
+## Why do AI coding agents need gates?
 
-### Fedora, RHEL-family, openSUSE
+Your agent writes code faster than you review it. Studies and dev surveys keep finding the same failures:
 
-Download the GitHub release RPM asset and install it with your distro-native command:
+- Plausible code with wrong logic
+- Imports of packages which don't exist
+- Outdated APIs from training cutoffs
+- "Done" claims with zero proof
 
-```bash
-sudo dnf install ./meta-architect-<version>-1.noarch.rpm
-# or
-sudo zypper install ./meta-architect-<version>-1.noarch.rpm
-```
+Meta-Architect blocks each one:
 
-These packages install the Meta-Architect payload and expose `ma` / `meta-architect`, but the product still runs inside a Codex-native session. They do not create a separate desktop or terminal product.
+- No architecture without a decision record. `$arch` writes the blueprint and the trade-offs.
+- No stack claims without evidence. `$sage` grades every dependency claim VERIFIED, PARTIAL, or MISSING against upstream repos through GitMCP.
+- No build while a gate is red. Logic, security, and DX reviews fail closed.
+- No release claims without proof. Releases need issue-linked, production-verified evidence.
 
-### npm fallback
+## What is Meta-Architect?
 
-```bash
-# Install
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+An open-source workflow governor for AI coding agents. You install it as a skill package in your agent host. It adds six gated lanes plus `$maestro`, a bounded manager which routes your work through them. It doesn't replace your agent, runtime, or model. It governs what they produce.
 
-# Start Codex context if needed
-ma --madmax --high
-
-# Remove Meta-Architect only
-npm uninstall -g @jstn-sdk/ma
-
-# Remove Meta-Architect and Codex
-npm uninstall -g @jstn-sdk/ma @openai/codex
-```
-
-What this assumes:
-
-- Codex is installed globally
-- Meta-Architect is installed globally as the skills/plugin package
-- Meta-Architect installs its published skill surface into the active Codex home
-- the product experience happens through the skill workflow inside Codex
-
-> [!IMPORTANT]
-> On Linux, distro-native package install is the default surface.
-> npm remains available as a fallback path.
-
-## Repository Branch Strategy
-
-Meta-Architect’s repository workflow follows a stricter release posture focused on gated promotion:
-
-- `main` = release-facing protected branch
-- `development` = normal integration branch
-- `feature/*` = short-lived contribution branches
-- contributors branch from `development`
-- normal PRs target `development`
-- only curated promotions move `development` into `main`
-
-> [!CAUTION]
-> `main` is intended to be protected and exceptional.
-> Maintainers should stop bypass-pushing to `main` except for genuine emergency or admin recovery cases.
-
-## Setup
-
-### Package setup
-
-Debian-family install:
+| Fact | Value |
+| --- | --- |
+| Type | Skill and plugin package for AI coding agent hosts |
+| Reference host | Codex (full support) |
+| Compatibility scope | Codex, OpenCode, Gemini CLI, Amp, Claude Code, Goose, Hermes, Pi, Cursor, Windsurf, Cline, Continue, Roo, Kiro CLI, Junie, GitHub Copilot, and Antigravity ([coverage evidence](./docs/agent-compat-integration-report.md)) |
+| Runtime | Node.js 20+ |
+| Install | `npm i -g @jstn-sdk/ma` |
+| Evidence sources | GitMCP / MCP endpoints |
+| License | MIT |
 
-```bash
-sudo apt install ./meta-architect_<version>_all.deb
-```
+## How does it work?
 
-Arch-family install:
+State your intent once. `$maestro` picks the next safe step and stops when something fails.
 
-```bash
-sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
+```text
+$maestro I want to build: a multi-tenant analytics API for logistics customers
 ```
 
-Fedora/openSUSE install:
-
-```bash
-sudo dnf install ./meta-architect-<version>-1.noarch.rpm
+```text
+Meta-Architect Status
+=====================
+Idea: CLEAR
+Architecture: APPROVED
+Evidence: VERIFIED
+Logic: GREEN
+Security: GREEN
+Experience: GREEN
+Build: LOCKED
 ```
 
-npm fallback:
+Build stays LOCKED until every upstream gate passes. Red stays red.
 
-```bash
-# Install
-npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+## The six gates
 
-# Launch
-ma --madmax --high
+| Lane | Question it answers | Gate |
+| --- | --- | --- |
+| `$arch` | What are you building, and why this shape? | architecture_status |
+| `$sage` | Do your stack choices trace to real upstream evidence? | evidence_status |
+| `$flow` | Do the logic and state transitions hold? | logic_status |
+| `$vet` | Does it survive security and dependency review? | security_status |
+| `$vibe` | Will developers and users tolerate it? | experience_status |
+| `$build` | What's the narrowest safe thing to build now? | build_status |
 
-# Remove Meta-Architect only
-npm uninstall -g @jstn-sdk/ma
+Four helpers support the lanes without moving gates: `$align`, `$diagnose`, `$tdd`, `$cleanup`.
 
-# Remove Meta-Architect and Codex
-npm uninstall -g @jstn-sdk/ma @openai/codex
-```
+## How is it different from Spec Kit, BMAD, or Agent OS?
 
-This gives you:
+Spec-driven tools structure what your agent writes. Meta-Architect enforces what your agent proves.
 
-- the installed Meta-Architect skill surface
-- the canonical Meta-Architect skill entrypoints inside a Codex session
-- the optional `ma` helper command when a guided start is useful
+| | Spec Kit | BMAD | Agent OS | Meta-Architect |
+| --- | --- | --- | --- | --- |
+| Structured workflow | Yes | Yes | Yes | Yes |
+| Gates which block | No | No | No | Yes |
+| External evidence verification | No | No | No | Yes, GitMCP-graded |
+| Learning loop with promotion rules | No | No | No | Yes |
+| Multi-host | Yes | Yes | Yes | Codex today, expanding |
 
-### Contributor setup: source checkout
+Already using a spec tool? Keep it. Their specs become inputs. MA's gates verify the execution.
 
-Use this path only if you want to work on Meta-Architect itself.
+## Quick start
 
 ```bash
-git clone https://github.com/JustineDevs/meta-architect.git
-cd meta-architect
-npm install
-npm link
-```
-
-`npm link` makes `ma` and `meta-architect` available from the local checkout.
-
-## Quick Start
+# 1. Install (macOS, Linux, WSL, Git-Bash)
+curl -fsSLo install.sh https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh && curl -fsSLo install.sh.sha256 https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh.sha256 && sed 's#scripts/install.sh#install.sh#' install.sh.sha256 | sha256sum -c - && sh install.sh
 
-### 1. Start Codex context if needed
-
-```bash
+# 2. Launch Codex
 ma --madmax --high
-```
-
-### 2. Start with the real usage-workflow prompt
 
-Use the same operator shape defined in [example/usage-workflow.md](./example/usage-workflow.md).
-
-Quick-start prompt:
-
-```text
-$maestro
-
-Or start directly with:
-
-$arch I want to build: [PROJECT IDEA]
-
-Context:
-- Product type: [web app / mobile app / API / marketplace / agent system / internal tool]
-- Users: [who will use it]
-- Core problem: [what problem it solves]
-- Main features:
-  1. [feature one]
-  2. [feature two]
-  3. [feature three]
-- Constraints:
-  - Budget: [low / medium / high]
-  - Team size: [solo / small / medium]
-  - Timeline: [e.g. 2 weeks MVP, 3 months beta]
-  - Preferred stack: [optional]
-  - Avoid: [optional]
-- Quality priorities:
-  - [e.g. speed, low cost, security, DX, maintainability, scalability]
-- Deployment target:
-  - [Vercel / Docker / VPS / AWS / GCP / local-first / hybrid]
-
-Required output:
-1. Problem framing
-2. Recommended architecture
-3. Stack decision with justification
-4. System components and responsibilities
-5. Data model and storage choices
-6. Auth/security considerations
-7. DX/UX considerations
-8. Delivery plan for v0.1.12
-9. Risks and trade-offs
-10. Decision log
-11. Exact next trigger to run after this
+# 3. State your intent inside the session
+$maestro I want to build: [your project idea]
 ```
 
-### 3. Run the full trigger sequence inside Codex
+### AI agent installation prompt
 
-The singular umbrella in-session entry point is `$maestro`. It is the bounded autonomous manager for the in-session workflow. The package does not ship a separate `$meta-architect` skill.
-
-The release-gated sequence stays fixed:
-
-```text
-$arch
-$sage
-$flow
-$vet
-$vibe
-$build
-```
-
-Optional publishable non-gating helper skills available around that sequence:
+Copy and paste this prompt into your AI coding agent:
 
 ```text
-$align
-$diagnose
-$tdd
-$cleanup
-```
-
-See [example/usage-workflow.md](./example/usage-workflow.md) for the full prompt templates for each step.
-
-### 4. Secondary helper path
+Install Meta-Architect for this project.
 
-If you are working from a repository directly and need scaffolded local support files, use:
+1. Detect the current AI host and its native project configuration surface.
+2. Install or update `@jstn-sdk/ma@latest` using the host's supported package manager.
+3. Set `MA_AGENT` to the detected host ID when a host-specific surface is available.
+4. Run `ma setup` and accept the detected project scope and targets.
+5. Verify the generated `.ma/` state and native host artifacts.
+6. Report the installed version, selected host, generated files, and any unsupported capabilities.
 
-```bash
-ma bootstrap
-ma bootstrap --init-mcp
-ma doctor
-ma setup
-ma
-```
-
-Recommended lazy-user path:
-- run `ma bootstrap` first to repair packaged assets, scaffold local runtime files, and verify the environment
-- add `--init-mcp` if you want starter GitMCP source files written into the local `mcp/` folder when it is empty or invalid
-- use `ma doctor` later when you want a check-only readiness report without changing files
-
-Expected output for `ma setup`:
-
-```text
-meta-architect setup
-====================
-ready: .codex/agents
-ready: .codex/prompts
-ready: .ma/skills
-ready: .ma/evidence
-ready: .ma/context
-ready: .ma/specs
-ready: .ma/plans
-ready: mcp
-ready: docs
-ready: docs/qa
-ready: sprint
+Do not overwrite user-owned files, modify unrelated configuration, or claim a host is supported without verification.
 ```
 
-### 5. Configure GitMCP sources
+Windows PowerShell: `npm i -g @openai/codex@latest @jstn-sdk/ma@latest`
+More install options: [docs/getting-started.md](./docs/getting-started.md)
 
-Add real repository-backed endpoints in `mcp/servers.json`.
+Uninstall Meta-Architect: `npm uninstall -g @jstn-sdk/ma`
+Uninstall Meta-Architect and Codex: `npm uninstall -g @jstn-sdk/ma @openai/codex`
 
-Example:
-
-```json
-{
-  "category": "candidate",
-  "repo": "owner/repo",
-  "endpoint": "https://gitmcp.io/owner/repo"
-}
-```
+### Install into an AI vendor host
 
-Recommended source-selection posture:
-
-- use packaged native references to narrow candidate families first
-- map serious candidates to exact upstream GitMCP endpoints
-- verify final choices against upstream repos and official docs before approval
-
-Core discovery standard:
-
-- `https://ossium.live/home`
-- use Ossium to discover trending OSS, curated repos, YC-backed repos, GSoC orgs, and contribution opportunities faster
-- `https://trendshift.io/`
-- use Trendshift for rising GitHub engagement and topic-driven trend discovery
-- `https://devhunt.org/`
-- use Dev Hunt for recently launched developer tools and current dev-tool discovery
-- `https://libraries.io/`
-- use Libraries.io for package and dependency metadata, with caution because its public data is scraped and not validated/curated for accuracy
-- `https://openhub.net/`
-- use Open Hub for project activity, contributor, popularity, and comparison signals
-- `https://www.opensourceprojects.dev/`
-- use Open-source Projects for curated OSS discovery and detailed project writeups
-- treat all of these as discovery acceleration, then convert promising finds into exact upstream GitMCP mappings and official-doc checks for `$sage`
-
-Useful native references:
-
-- `skills/maestro/references/native-ingest-map.md`
-- `skills/sage/references/source-selection.md`
-- `skills/vet/references/security-playbooks.md`
-
-Canonical `$sage` order:
-
-1. Start with the upstream repo and official docs if you already know them.
-2. Use discovery accelerators only when you need help finding or narrowing candidates.
-3. Map selected candidates to exact upstream GitMCP endpoints.
-4. Verify against upstream repos and official docs before treating anything as approved evidence.
-
-> [!IMPORTANT]
-> Verified release evidence must come from repository-form GitMCP endpoints such as `https://gitmcp.io/{owner}/{repo}`.
-> A generic documentation endpoint such as `https://gitmcp.io/docs` does not count as VERIFIED evidence for build unlocking.
-> Discovery surfaces such as Ossium, Trendshift, Dev Hunt, Libraries.io, Open Hub, and Open-source Projects are not substitutes for upstream repo or official-doc verification.
-
-### 6. Secondary helper flow outside Codex
-
-If you need scripted repo-local validation rather than the interactive runtime workflow:
+Install Meta-Architect once, then select the host surface before launch. The
+pre-launch step detects installed hosts and writes the selected scope and
+targets to `.ma/prelaunch.json`.
 
 ```bash
-ma idea "Build a real-time collaborative whiteboard for product teams"
-ma run '$arch'
-ma run '$sage'
-ma run '$flow'
-ma run '$vet'
-ma run '$vibe'
-ma status
-ma run '$build'
-```
-
-Expected status before the helper-path `$build`:
-
-```text
-Meta-Architect Status
-=====================
-Idea: CLEAR
-Architecture: APPROVED
-Evidence: VERIFIED
-Logic: GREEN
-Security: GREEN
-Experience: GREEN
-Build: LOCKED
-Next allowed triggers:
-$build
-```
-
-Expected helper-path build output:
-
-```text
-Build gate is green.
-Suggested branches:
-- feature/implementation
-- feature/verification
-Optional worktree commands:
-git worktree add ../implementation feature/implementation
-git worktree add ../verification feature/verification
-```
-
-### 7. Simple command guide
-
-Meta-Architect has two surfaces.
-
-- terminal helper commands
-- in-session skills
+# Codex (reference host)
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+ma --madmax --high
 
-The umbrella in-session entry point is `$maestro`. There is no separate shipped `$meta-architect` skill surface.
+# Claude Code
+MA_AGENT=claude-code npm i -g @jstn-sdk/ma@latest
+MA_AGENT=claude-code ma --madmax --high
 
-Terminal commands are normal shell commands you run in the terminal:
+# Cursor
+MA_AGENT=cursor npm i -g @jstn-sdk/ma@latest
+MA_AGENT=cursor ma --madmax --high
 
-```bash
-ma setup
-ma init
-ma idea "Build a product"
-ma status
-ma run '$arch'
+# Any registered host surface
+MA_AGENT=<host-id> npm i -g @jstn-sdk/ma@latest
+MA_AGENT=<host-id> ma --madmax --high
 ```
 
-In-session skills are prompts you use inside the Codex conversation after launch:
+MA installs or reuses the native skill/configuration surface for the selected
+host and keeps the canonical workflow unchanged. See the [host compatibility
+evidence](./docs/agent-compat-integration-report.md) and [skills publishing
+guide](./docs/skills-publishing.md) for the complete registry and distribution
+rules.
 
-```text
-$maestro
-$arch
-$sage
-$flow
-$vet
-$vibe
-$build
-$align
-$diagnose
-$tdd
-$cleanup
-```
+## Who is it for?
 
-Plain-language difference:
-- `ma ...` = helper commands in the terminal
-- `$...` = the product experience inside Codex
-
-Autonomous-manager contract:
-- `$maestro` is the only umbrella in-session surface
-- it manages the next allowed step and lane handoff, but it does not replace the gated outputs owned by `$arch -> $sage -> $flow -> $vet -> $vibe -> $build`
-- `$align`, `$diagnose`, `$tdd`, and `$cleanup` are publishable helper skills that do not move release gates
-
-What `ma setup` and `ma init` do:
-- both currently do the same thing
-- they create the local support files and folders
-- they prepare `.ma/` runtime files such as context, specs, plans, evidence, and runbook files
-- they do not run the skill workflow by themselves
-
-What `ma bootstrap` does:
-- checks whether `codex` is callable
-- repairs installed skills and support-bundle assets when possible
-- runs local scaffold setup
-- can seed starter MCP files with `--init-mcp` when the local MCP config is empty or invalid
-- reports `READY`, `READY_WITH_WARNINGS`, or `BLOCKED`
-
-What `ma doctor` does:
-- runs the same environment checks without changing files
-- prints the current readiness state and exact next step
-
-What to use when:
-- use Codex and run the skills in-session
-- use `$maestro` when you want Meta-Architect to choose the best next step for you or act as the bounded autonomous manager for the umbrella workflow
-- use `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` inside the Codex session
-- use `$align`, `$diagnose`, `$tdd`, or `$cleanup` when a helper is enough and the release gate should stay where it is
-- use `ma bootstrap` when you want the lazy-user setup path
-- use `ma doctor` when you want a check-only environment report
-- use `ma setup` or `ma init` only when you want local scaffolding or scripted helper automation from the terminal
-- use `ma sdk-path` when you need the exact installed support-bundle path for packaged prompts, MCP files, sprint files, scripts, plugin metadata, or templates
-
-## Skill Surface
-
-Meta-Architect’s in-session surface has three layers:
-
-- umbrella autonomous manager: `$maestro`
-- fixed gated lanes: `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build`
-- non-gating helper skills: `$align`, `$diagnose`, `$tdd`, `$cleanup`
-
-Helper skills are publishable surfaces, but they do not own release-state transitions.
-
-## Core Maintainers
-
-<table>
-  <tr>
-    <td><strong>Role</strong></td>
-    <td><strong>Name</strong></td>
-    <td><strong>GitHub</strong></td>
-  </tr>
-  <tr>
-    <td>Creator / Maintainer</td>
-    <td>JustineDevs</td>
-    <td><a href="https://github.com/JustineDevs">@JustineDevs</a></td>
-  </tr>
-</table>
-
-## Gated Lanes
-
-| Trigger | Purpose | Main output | Gate effect |
-| --- | --- | --- | --- |
-| `$arch` | Produce the first-pass architecture blueprint | decision entry | `architecture_status = APPROVED` |
-| `$sage` | Ground major choices in configured GitMCP evidence | evidence records | `evidence_status = VERIFIED | PARTIAL | MISSING` |
-| `$flow` | Review baseline logic and state transitions | logic review entry | `logic_status = GREEN | RED` |
-| `$vet` | Run baseline security and dependency review | audit and CVE records | `security_status = GREEN | RED` |
-| `$vibe` | Review developer and user experience implications | DX/UX outcome record | `experience_status = GREEN | RED | WAIVED` |
-| `$build` | Unlock bounded build planning | build-ready decision + `.ma/plans/build.md` | `build_status = READY` |
-
-## Helper Skills
-
-| Trigger | Purpose | Gate effect |
-| --- | --- | --- |
-| `$align` | Normalize terminology, tighten scope, and improve prompt or docs clarity | none |
-| `$diagnose` | Decompose blocked-lane symptoms into hypotheses and next probes | none |
-| `$tdd` | Lock behavior with regression-first or test-first scaffolding | none |
-| `$cleanup` | Simplify noisy output and run a final-pass anti-slop cleanup | none |
+- Solo builders shipping with AI agents who want release discipline without enterprise process
+- OSS contributors who need stack decisions they defend in review
+- Skip it if you want an unattended agent writing code. MA governs your agent. It isn't one.
 
-## Gate Model
+## How do I contribute?
 
-Meta-Architect is intentionally fail-closed.
+1. Open an issue before a PR. It saves rework.
+2. Start here: [issues labeled `triage`](https://github.com/JustineDevs/meta-architect/issues)
+3. Branch from `development`. `main` is protected and release-facing.
+4. Run `npm test` before you submit. Follow [AGENTS.md](./AGENTS.md).
+5. AI-assisted PRs welcome. Explain every line you submit or expect a close.
 
-| Status | Meaning |
-| --- | --- |
-| `CLEAR` | enough input exists to proceed |
-| `APPROVED` | the architecture lane produced an acceptable first-pass blueprint |
-| `VERIFIED` | live evidence was grounded through approved GitMCP sources |
-| `PARTIAL` | evidence is configured but live proof is incomplete or unavailable |
-| `GREEN` | the current baseline review passed |
-| `RED` | the lane is blocked or failed |
-| `WAIVED` | the lane was intentionally waived with a recorded reason |
-| `LOCKED` | downstream work is not allowed yet |
-| `READY` | the next gated step is allowed |
-
-> [!CAUTION]
-> `$build` must stay locked until the upstream release state in `.ma/release.json` satisfies the gate contract.
-> Meta-Architect is designed to stop on blockers rather than silently continue.
-> Rich runtime artifacts live in `.ma/context/`, `.ma/specs/`, `.ma/plans/`, and `.ma/runbook.md`.
-
-## Release and Packaging
-
-Meta-Architect has three related but different distribution surfaces.
-
-| Surface | Purpose | Produced by |
-| --- | --- | --- |
-| Linux native packages | distro-managed install assets for Debian-family and Arch-family environments | `npm run linux:packages:build` and GitHub release assets |
-| npm package | public package containing the installable Meta-Architect skills/plugin system, docs, scripts, and canonical skills | `npm publish` or `npm pack` |
-| skills bundle | narrower tarball containing `skills/` only | `npm run skills:pack` |
-
-Required packaging commands:
+## Learn more
 
-```bash
-npm run skills:manifest
-npm run skills:validate
-npm run skills:pack
-npm run skills:install -- --path ./dist/installed-skills
-npm run linux:packages:build
-npm run release:assets
-npm run pack:inspect
-```
-
-Pre-publish rules:
-
-- `skills/index.json` must be current
-- `npm run skills:validate` must pass
-- `dist/meta-architect-skills.tgz` must exist
-- `dist/meta-architect_<version>_all.deb` must exist for Debian-family installs
-- `dist/meta-architect-<version>-1-any.pkg.tar.xz` must exist for Arch-family installs
-- `dist/meta-architect-<version>-1.noarch.rpm` must exist for Fedora/openSUSE-style installs
-- `npm pack --dry-run` must show only intended public files
-- docs must match the real skills/plugin and release behavior
-
-Release lane discipline:
-- stable versions publish to npm `latest`
-- prerelease versions such as `0.2.0-beta.1` must publish with an explicit dist-tag such as `beta`
-- alternate lanes such as `next`, `beta`, and `canary` must never overwrite `latest`
-
-Maintainer version-bump flow:
-1. Bump the package with `npm version <version> --no-git-tag-version`
-2. Update `CHANGELOG.md`, `RELEASE.md`, and `docs/qa/release-readiness-<version>.md`
-3. Run `npm run release:verify`
-4. Run `npm run release:check`
-5. Create and push tag `v<version>`
-6. Build and smoke-check the Linux native packages with `npm run linux:packages:build`, `npm run linux:packages:smoke`, and `npm run release:assets` on Linux
-7. Preferred publish path: publish from `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
-7. Local shell fallback when not publishing from GitHub Actions or GitLab CI/CD:
-   - Stable publish: `npm publish --access public`
-   - Prerelease publish: `npm publish --access public --tag <lane>`
-8. Verify publish state with `npm view @jstn-sdk/ma version dist-tags time --json`
-9. Confirm the GitHub release includes `dist/meta-architect-skills.tgz`, `meta-architect_<version>_all.deb`, `meta-architect-<version>-1-any.pkg.tar.xz`, and `meta-architect-<version>-1.noarch.rpm`
-
-Provenance note:
-- `npm publish --provenance` requires a supported cloud CI/CD provider
-- a local shell publish will fail with `Automatic provenance generation not supported for provider: null`
-- use the repository publish workflow when provenance is required
-
-Release automation:
-- `npm run release:sync` bumps and synchronizes the active release line only when watched release-relevant files changed
-- `npm run release:advance` force-bumps the next patch line and rewrites the same version-bearing files
-- `.github/workflows/release-sync.yml` runs the sync path on `main` pushes that touch watched release-relevant paths
-- `.github/workflows/release-advance.yml` runs after a published GitHub release and advances the repo to the next patch line automatically
-
-> [!CAUTION]
-> Do not claim npm, GitHub release, or any other publish channel until that channel has actually succeeded.
-> Release documentation must match reality, not intent.
-
-## Package Surface
-
-<table>
-  <tr>
-    <td><strong>Included</strong></td>
-    <td><code>bin/</code>, <code>skills/</code>, <code>docs/</code>, <code>scripts/</code>, <code>index.js</code>, <code>README.md</code>, <code>LICENSE</code></td>
-  </tr>
-  <tr>
-    <td><strong>Excluded</strong></td>
-    <td><code>.ma/</code> runtime state, context, specs, plans, logs, caches, and temp install outputs</td>
-  </tr>
-</table>
-
-## Repository Structure
-
-<table>
-  <tr>
-    <td><strong>Path</strong></td>
-    <td><strong>Responsibility</strong></td>
-  </tr>
-  <tr>
-    <td><code>.codex/</code></td>
-    <td>runtime prompts, hooks, and repo guidance</td>
-  </tr>
-  <tr>
-    <td><code>skills/</code></td>
-    <td>canonical public skill contracts</td>
-  </tr>
-  <tr>
-    <td><code>plugins/meta-architect/</code></td>
-    <td>plugin-oriented distribution surface</td>
-  </tr>
-  <tr>
-    <td><code>docs/</code></td>
-    <td>installation, publishing, and release documentation</td>
-  </tr>
-  <tr>
-    <td><code>missions/</code></td>
-    <td>reproducible scenario-driven workflows</td>
-  </tr>
-  <tr>
-    <td><code>mcp/</code></td>
-    <td>GitMCP endpoint and collection configuration</td>
-  </tr>
-  <tr>
-    <td><code>scripts/</code></td>
-    <td>validation, packing, and install helpers</td>
-  </tr>
-  <tr>
-    <td><code>sprint/</code></td>
-    <td>human-readable phased workflow documents</td>
-  </tr>
-</table>
-
-## Documentation
-
-| Surface | Purpose |
-| --- | --- |
-| [Getting Started](./docs/getting-started.md) | end-to-end local onboarding |
-| [Skills Reference](./docs/skills.md) | trigger-by-trigger contract guide |
-| [Installed Support Bundle](./docs/installed-sdk.md) | standard packaged asset path for skills and helper flows |
-| [Skills Publishing](./docs/skills-publishing.md) | source-to-package pipeline |
-| [MCP Setup](./docs/mcp-setup.md) | evidence endpoint policy |
-| [Plugin README](./plugins/meta-architect/README.md) | plugin distribution surface |
-| [Collaborative Whiteboard Mission](./missions/collaborative-whiteboard/mission.md) | concrete scenario walkthrough |
-| [Release Spec](./docs/release-spec.md) | release and gate policy |
-| [Release Readiness](./docs/qa/release-readiness-0.1.12.md) | QA evidence for the `v0.1.12` line |
-
-## Release Hygiene
-
-> [!WARNING]
-> Runtime `.ma` logs, state, tmp, and cache files must not be shipped.
-> Public docs must match actual package behavior.
-> Publish statements must match reality.
-> Skill contracts must stay aligned across canonical and plugin-facing copies.
+- [Getting Started](./docs/getting-started.md)
+- [Skills Reference](./docs/skills.md)
+- [Demo](./DEMO.md)
+- [Coverage Matrix](./COVERAGE.md): the proof behind every claim on this page
+- [Release Spec](./docs/release-spec.md)
+- [Disk-Bounded Test and Review Runs](./docs/disk-optimization.md)
+- [MCP Setup](./docs/mcp-setup.md)
 
 ## License
 
-[MIT](./LICENSE)
+[MIT](./LICENSE). Built by [@JustineDevs](https://github.com/JustineDevs). Shaped by ideas from the `oh-my-codex` ecosystem.
+
+Found a bad claim before it shipped? Star the repo. It helps other developers find it.