@jstn-sdk/ma 0.1.11 → 0.1.13

package/docs/getting-started.md

@@ -20,9 +20,36 @@ By the end of this guide you should be able to:
 - an MCP-capable runtime
 - network access if you want live `$sage` verification against a real GitMCP server
 
-## 1. Canonical install and launch
+## 1. Default install and launch
 
-Canonical public install:
+Recommended CLI install for macOS, Linux, WSL, and Git-Bash:
+
+```bash
+# One-line install (POSIX shells only; use WSL/Git-Bash on Windows)
+curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh
+```
+
+The jsDelivr installer runs `npm i -g @openai/codex@latest @jstn-sdk/ma@latest`, then `ma setup`.
+
+Debian-family install:
+
+```bash
+sudo apt install ./meta-architect_<version>_all.deb
+```
+
+Arch-family install:
+
+```bash
+sudo pacman -U ./meta-architect-<version>-1-any.pkg.tar.xz
+```
+
+Fedora/openSUSE install:
+
+```bash
+sudo dnf install ./meta-architect-<version>-1.noarch.rpm
+```
+
+Default supported npm fallback:
 
 ```bash
 # Install
@@ -38,11 +65,11 @@ npm uninstall -g @jstn-sdk/ma
 npm uninstall -g @jstn-sdk/ma @openai/codex
 ```
 
-That is the default product path. The product experience is the in-session skill workflow in [example/usage-workflow.md](../example/usage-workflow.md). The `ma` command is only a helper for starting or supporting that flow.
+The jsDelivr CLI installer is the recommended quick-start path for POSIX shells. Linux-native distro packages remain supported release assets, and the npm path remains the canonical package install underneath the installer. The product experience is still the in-session skill workflow in [example/usage-workflow.md](../example/usage-workflow.md). The `ma` command is only a helper for starting or supporting that flow.
 
 ## 2. Real usage workflow
 
-Start with the structured `$arch` prompt:
+Start with `$maestro` when you want the bounded autonomous manager to inspect the workflow state and choose the next step. Start with the structured `$arch` prompt when you already know architecture is the next gated lane:
 
 ```text
 $arch I want to build: [PROJECT IDEA]
@@ -74,7 +101,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.11
+8. Delivery plan for v0.1.13
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -92,6 +119,17 @@ $build
 
 Use the full prompt blocks from [example/usage-workflow.md](../example/usage-workflow.md) when you want the exact handoff format between lanes.
 
+Optional helper skills around that path:
+
+```text
+$align
+$diagnose
+$tdd
+$cleanup
+```
+
+These helpers are publishable skills, but they do not change gate ownership, move release states, or replace the fixed release sequence.
+
 ## 3. Contributor clone and link
 
 ```bash
@@ -150,6 +188,8 @@ Meta-Architect works in two simple ways:
 - terminal commands
 - in-session skills
 
+The umbrella in-session entry point is `$maestro`. The package does not ship a separate `$meta-architect` skill surface.
+
 Terminal commands are normal shell commands:
 
 ```bash
@@ -170,12 +210,22 @@ $flow
 $vet
 $vibe
 $build
+$align
+$diagnose
+$tdd
+$cleanup
 ```
 
 Easy rule:
 - `ma ...` = terminal helper command
 - `$...` = in-session skill
 
+Contract split:
+- terminal helper commands support setup, local state, and scripted verification
+- in-session skills are the product workflow surface
+- `$maestro` is the only umbrella surface inside the session
+- `$align`, `$diagnose`, `$tdd`, and `$cleanup` stay publishable but non-gating
+
 `ma setup` and `ma init` currently do the same thing:
 - they create local `.ma/` support files
 - they prepare context, specs, plans, evidence, and runbook files
@@ -205,16 +255,16 @@ Minimum live example:
 
 ```json
 {
-  "category": "meta-list",
-  "repo": "sindresorhus/awesome",
-  "endpoint": "https://gitmcp.io/sindresorhus/awesome"
+  "category": "candidate",
+  "repo": "owner/repo",
+  "endpoint": "https://gitmcp.io/owner/repo"
 }
 ```
 
-Recommended first set:
-- `sindresorhus/awesome`
-- `dzharii/awesome-typescript`
-- `sbilly/awesome-security`
+Recommended source-selection posture:
+- use the packaged native references to narrow candidate families first
+- map serious candidates to exact upstream GitMCP repo endpoints
+- verify final choices against upstream repos and official docs before treating them as approved evidence
 
 Core discovery standard:
 - use `https://ossium.live/home` to find trending OSS, curated repos, YC-backed repos, GSoC orgs, and contribution leads faster than browsing GitHub directly
@@ -225,6 +275,11 @@ Core discovery standard:
 - use `https://www.opensourceprojects.dev/` to inspect curated OSS selections and detailed project writeups
 - move any promising discovery result into `mcp/servers.json` as an exact upstream GitMCP repo endpoint before treating it as VERIFIED evidence
 
+Useful native reference packs:
+- `skills/maestro/references/native-ingest-map.md`
+- `skills/sage/references/source-selection.md`
+- `skills/vet/references/security-playbooks.md`
+
 Canonical `$sage` order:
 - known upstream repo/docs first
 - discovery accelerators second
@@ -236,7 +291,7 @@ See [docs/mcp-setup.md](./mcp-setup.md) for endpoint policy and evidence semanti
 ## 6. Secondary helper flow
 
 ```bash
-ma idea "Build a real-time collaborative whiteboard for product teams"
+ma idea "Prepare Meta-Architect v0.1.13 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
 ```
 
 Expected effects:
@@ -249,7 +304,7 @@ If this fails:
 
 ## 7. Run the helper skill sequence
 
-### 5.0 Workflow manager
+### 7.1 Autonomous manager
 
 ```bash
 ma run '$maestro'
@@ -257,7 +312,10 @@ ma run '$maestro'
 
 Expected effects:
 - reads the current gate state
-- recommends the best next step
+- acts as the bounded umbrella in-session workflow manager
+- recommends the best next step or lane assignment
+- can hand work to a publishable non-gating helper skill when that is enough
+- does not move release gates by itself
 - writes `.ma/plans/maestro.md`
 - records an advisory decision entry
 
@@ -265,7 +323,13 @@ Generated or updated:
 - `.ma/decisions.json`
 - `.ma/plans/maestro.md`
 
-### 5.1 Architecture
+Optional non-gating helper skills that can run before or between gated lanes:
+- `$align` for scope/language cleanup
+- `$diagnose` for blocked-lane triage
+- `$tdd` for regression-first execution setup
+- `$cleanup` for simplification and final-pass polish
+
+### 7.2 Architecture
 
 ```bash
 ma run '$arch'
@@ -282,7 +346,7 @@ Generated or updated:
 - `.ma/specs/architecture.md`
 - `.ma/plans/implementation.md`
 
-### 5.2 Evidence
+### 7.3 Evidence
 
 ```bash
 ma run '$sage'
@@ -311,7 +375,7 @@ If this fails:
 - verify network access
 - rerun after correcting the endpoint or environment
 
-### 5.3 Logic
+### 7.4 Logic
 
 ```bash
 ma run '$flow'
@@ -325,7 +389,7 @@ Expected effects:
 Generated or updated:
 - `.ma/specs/logic.md`
 
-### 5.4 Security
+### 7.5 Security
 
 ```bash
 ma run '$vet'
@@ -339,7 +403,7 @@ Expected effects:
 Generated or updated:
 - `.ma/specs/security.md`
 
-### 5.5 Experience
+### 7.6 Experience
 
 ```bash
 ma run '$vibe'
@@ -395,11 +459,11 @@ Expected output shape:
 ```text
 Build gate is green.
 Suggested branches:
-- feature/ui
-- feature/api
+- feature/implementation
+- feature/verification
 Optional worktree commands:
-git worktree add ../ui feature/ui
-git worktree add ../api feature/api
+git worktree add ../implementation feature/implementation
+git worktree add ../verification feature/verification
 ```
 
 If `$build` fails:
@@ -408,11 +472,11 @@ If `$build` fails:
 - fix the corresponding upstream lane
 - rerun that lane, then rerun `$build`
 
-## 10. Example walkthrough: collaborative whiteboard
+## 10. Example walkthrough: MA release hardening
 
 ```bash
 ma setup
-ma idea "Build a collaborative whiteboard with live cursors and shared boards"
+ma idea "Prepare Meta-Architect v0.1.13 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
 ma run '$arch'
 ma run '$sage'
 ma run '$flow'
@@ -425,17 +489,17 @@ ma run '$build'
 If you want an interactive Codex session during the walkthrough, start it separately with `ma`.
 
 What should happen:
-- `$arch` records a structured first-pass blueprint
-- `$sage` binds major choices to configured GitMCP-backed sources
-- `$flow` records the kernel’s baseline state review for the mission
-- `$vet` records a baseline security review
-- `$vibe` records baseline DX/UX guidance
-- `$build` suggests bounded concerns like `feature/ui` and `feature/api`
+- `$arch` records the architecture and release-hardening blueprint
+- `$sage` binds package, Obsidian, prompt-strategy, and MCP choices to configured evidence sources
+- `$flow` records state-transition and gate-order review
+- `$vet` records security, package exposure, and provider-bound context review
+- `$vibe` records operator/demo/docs usability guidance
+- `$build` suggests bounded implementation and verification branches after gates pass
 
-Related mission:
-- [missions/collaborative-whiteboard/mission.md](../missions/collaborative-whiteboard/mission.md)
+Canonical demo reference:
+- [DEMO.md](../DEMO.md)
 
-## 9. Merge and release path
+## 11. Merge and release path
 
 After implementation work is complete:
 
@@ -452,7 +516,7 @@ Expected effects:
   - `merge_status = MERGED_TO_DEVELOPMENT`
   - `release_status = SHIPPED_TO_PROD`
 
-## 10. Files generated or updated during a normal run
+## 12. Files generated or updated during a normal run
 
 - `.ma/decisions.json`
 - `.ma/release.json`
@@ -461,6 +525,13 @@ Expected effects:
 - `.ma/evidence/cves.json`
 - `.ma/evidence/outcomes.json`
 - `.ma/context/project.md`
+- `.ma/context/recording-core.json`
+- `.ma/context/learning-loop-core.json`
+- `.ma/context/workspace-context-pack.json`
+- `.ma/context/workspace-effectiveness.json`
+- `.ma/context/prompt-strategy-core.json`
+- `.ma/context/context-economy-core.json`
+- `.ma/context/obsidian-bridge.json`
 - `.ma/specs/architecture.md`
 - `.ma/specs/evidence.md`
 - `.ma/specs/logic.md`
@@ -472,7 +543,7 @@ Expected effects:
 
 These are local product artifacts created by the runtime. They are not a reason to bypass gate logic manually.
 
-## 11. If a gate fails
+## 13. If a gate fails
 
 Rule:
 - do not edit statuses manually

package/docs/installed-sdk.md

@@ -7,6 +7,8 @@ Meta-Architect installs two things into the active Codex home:
 
 The support bundle exists so skills and helper paths can use relevant packaged files without guessing where they live.
 
+The singular umbrella in-session skill is `maestro`. It is the bounded autonomous manager for the in-session workflow, and the installed skill set does not include a separate `meta-architect` skill folder.
+
 ## Canonical support bundle path
 
 Default:
@@ -30,12 +32,15 @@ ma sdk-path
 ## What is installed there
 
 - `mcp/`
+- `mcp/native-playbooks.json`
+- `mcp/local/playbooks.js`
 - `sprint/`
 - `prompts/`
 - `scripts/`
 - `plugins/meta-architect/`
 - `templates/`
 - `docs/README.md`
+- `docs/reference/` when packaged native reference packs are present
 - `asset-manifest.json`
 
 ## Why this exists
@@ -51,10 +56,28 @@ When Meta-Architect needs packaged support files, prefer the installed support b
 
 Examples:
 - MCP starter files -> `meta-architect-sdk/mcp/`
+- native playbooks manifest -> `meta-architect-sdk/mcp/native-playbooks.json`
+- read-only playbooks capability module -> `meta-architect-sdk/mcp/local/playbooks.js`
 - sprint references -> `meta-architect-sdk/sprint/`
 - Codex prompt assets -> `meta-architect-sdk/prompts/`
 - helper scripts -> `meta-architect-sdk/scripts/`
 - plugin metadata -> `meta-architect-sdk/plugins/meta-architect/`
 - templates -> `meta-architect-sdk/templates/`
+- bundled reference packs -> `meta-architect-sdk/docs/reference/`
 
 The in-session skill flow is still primary. This bundle only standardizes packaged asset access.
+
+Surface split:
+- in-session skills consume these packaged assets as product workflow inputs
+- terminal helper commands may inspect or scaffold against the same bundle, but they remain secondary support tooling
+- helper skills remain publishable and installable, but they do not own release-gate transitions
+
+## Playbooks contract
+
+`playbooks` is a first-party read-only local capability. Its packaged inputs live in the support bundle:
+
+- `mcp/native-playbooks.json` is the repo-owned curation manifest
+- `mcp/local/playbooks.js` is the packaged read-only resource surface
+- `docs/reference/` is where bundled native reference packs land when the release includes them
+
+Readiness should treat those assets as package-owned bundle contents, not as repo-local user setup steps or upstream mirrors.

package/docs/mcp-setup.md

@@ -3,7 +3,29 @@
 1. Use approved discovery accelerators when you need to find OSS candidates faster than browsing GitHub directly.
 2. Add repo-specific GitMCP endpoints in `mcp/servers.json` for any project you want to treat as approved evidence.
 3. Confirm categories in `mcp/collections.json`.
-4. Use `https://gitmcp.io/docs` only when no approved exact endpoint exists.
+4. Do not add `https://gitmcp.io/docs` to `mcp/servers.json`; verified evidence requires exact repo-form GitMCP endpoints only.
+
+## First-party local capabilities
+
+`mcp/local-capabilities.json` is separate from `mcp/servers.json`. It is the allowlist for Meta-Architect's packaged local capabilities:
+
+- `_state`
+- `memory`
+- `trace`
+- `team_run`
+- `code_intel`
+- `playbooks`
+
+`playbooks` is a read-only packaged capability. It does not point at external MCP servers and it does not repurpose `mcp/collections.json`.
+
+Its contract for this release is:
+
+- manifest: `mcp/native-playbooks.json`
+- module: `mcp/local/playbooks.js`
+- transport: `inproc`
+- behavior: packaged resource reads only, no mutating local tools
+
+If bootstrap or doctor reports a `playbooks` readiness warning, repair the packaged support bundle inputs rather than adding more GitMCP sources.
 
 ## Discovery vs verification
 
@@ -46,3 +68,45 @@ To move from discovery to VERIFIED evidence:
 - identify the upstream GitHub repository or official package/docs source from the discovery surface
 - map that repo to an exact `https://gitmcp.io/{owner}/{repo}` endpoint in `mcp/servers.json`
 - validate the choice against the upstream repo and official docs through `$sage`
+
+## Remote MCP transport
+
+`$sage` opens configured GitMCP endpoints as live MCP servers. Some remote MCP hosts reject direct SSE probes with HTTP 405 and require a host-supported remote MCP bridge. Meta-Architect treats that as a transport blocker, not as verified evidence.
+
+To enable bridge-backed live verification, configure a trusted local bridge command:
+
+```bash
+export MA_MCP_REMOTE_BRIDGE_CMD="mcp-remote {url}"
+```
+
+The `{url}` placeholder is replaced with the exact repo endpoint from `mcp/servers.json`. Use a preinstalled, trusted bridge binary or wrapper; do not depend on automatic package downloads in production verification.
+
+When no bridge is configured:
+- direct-SSE-compatible MCP servers can still verify normally
+- GitMCP 405 responses are recorded as bridge-required blockers
+- `evidence_status` remains `PARTIAL`, so `$flow` and `$build` stay locked
+
+## Separation of concerns
+
+- `mcp/servers.json` remains for repo-specific GitMCP evidence sources
+- `mcp/collections.json` remains GitMCP-oriented evidence categorization for this release
+- `mcp/local-capabilities.json` is the first-party in-process capability registry
+- `mcp/native-playbooks.json` is internal native curation metadata, not an upstream mirror or user-edited evidence source list
+
+## Current semantic source routing
+
+`mcp/collections.json` maps configured repository evidence into MA lanes.
+The current release intentionally includes both broad discovery lists and core-specific upstream sources.
+
+| Collection | Why it exists | Typical lanes |
+| --- | --- | --- |
+| `meta-list` and language collections | broad OSS candidate discovery before exact upstream selection | `$arch`, `$sage` |
+| `system-design` | architecture and flow reasoning references | `$arch`, `$sage`, `$flow`, `$build` |
+| `security` | trust-boundary and security review evidence | `$vet` |
+| `obsidian-api-docs` | Obsidian API evidence for vault, metadata, workspace, and plugin behavior | `$arch`, `$sage`, `$vibe` |
+| `obsidian-plugin-scaffold` | compatibility reference for MA's in-app Obsidian plugin surface | `$arch`, `$sage` |
+| `context-economy` | context-budget and terse-output source evidence | `$sage`, `$vet`, `$vibe`, `$build` |
+| `prompt-techniques` | prompt strategy source evidence for MA-owned prompt policies | `$arch`, `$sage`, `$flow`, `$vet`, `$vibe`, `$build` |
+
+Obsidian-derived notes remain `vault_context`.
+They do not count as `build_evidence` unless `$sage`, `$vet`, or another owning lane promotes a specific claim with source-backed proof.

package/docs/onboarding.md

@@ -12,6 +12,15 @@ This is the shortest entrypoint for the real first-run Meta-Architect path.
 
 ## Canonical install and start
 
+Recommended CLI install for macOS, Linux, WSL, and Git-Bash:
+
+```bash
+# One-line install (POSIX shells only; use WSL/Git-Bash on Windows)
+curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh
+```
+
+The installer uses jsDelivr to fetch this repo's POSIX install script and runs the canonical npm install path.
+
 ```bash
 # Install
 npm i -g @openai/codex@latest @jstn-sdk/ma@latest
@@ -28,7 +37,13 @@ npm uninstall -g @jstn-sdk/ma @openai/codex
 
 ## First runtime action
 
-Start with the structured `$arch` prompt from [example/usage-workflow.md](../example/usage-workflow.md):
+Start with `$maestro` when you want MA to choose and drive the next safe lane:
+
+```text
+$maestro
+```
+
+Use the structured `$arch` prompt from [example/usage-workflow.md](../example/usage-workflow.md) when you already know the project brief and want to begin directly with architecture:
 
 ```text
 $arch I want to build: [PROJECT IDEA]
@@ -48,7 +63,8 @@ Only use this when you need local repo scaffolding or scripted validation:
 ```bash
 ma setup
 ma
-ma idea "..."
+ma idea "Prepare Meta-Architect v0.1.13 for a production package release with real install docs, Obsidian brain-context support, learning-loop reliability, and package proof artifacts."
+ma run '$maestro'
 ma run '$arch'
 ma run '$sage'
 ma run '$flow'

package/docs/prompt-guidance-contract.md

@@ -0,0 +1,17 @@
+# Prompt Guidance Contract
+
+Meta-Architect prompt surfaces must preserve the Active Autonomy Core contract.
+
+## Required Patterns
+
+1. `AUTO-CONTINUE` and `ASK` must be named explicitly.
+2. The `ASK` list is closed: destructive, irreversible, credential-gated, external-production, materially scope-changing, or missing authority.
+3. Permission-handoff phrasing is banned on AUTO-CONTINUE branches.
+4. Skills and role prompts must describe completion as a loop with explicit stop conditions.
+5. Workflow terminal replies must name an outcome: `finished`, `blocked`, `failed`, `cancelled`, or `askuserQuestion`.
+6. Completion claims require fresh verification evidence or an explicit validation gap.
+7. Runtime hook policy must include stall-pattern coverage for passive permission handoffs.
+
+## Contributor Rule
+
+Do not weaken the anti-passive contract when editing prompts, skills, hooks, or exported host payloads. If a prompt surface cannot execute safely, it must name the exact closed-list ASK reason instead of asking a vague permission question.

package/docs/prompt-guidance-fragments/active-autonomy-core.md

@@ -0,0 +1,7 @@
+<!-- ACTIVE AUTONOMY CORE - DO NOT REMOVE -->
+- AUTO-CONTINUE: clear, already-requested, local/workspace-scoped, low-risk, reversible, non-destructive work with an available verification path. Continue executing, inspecting, editing, testing, and verifying without permission handoff.
+- ASK only for destructive, irreversible, credential-gated, external-production, materially scope-changing actions, or when missing authority blocks progress.
+- On AUTO-CONTINUE branches, do not say "Should I proceed?", "Would you like me to continue?", "If you want, I can ...", or equivalent permission-handoff phrasing. State the next action or evidence-backed result.
+- Do not instruct humans to perform ordinary safe reversible workspace actions; execute them through MA/runtime tools and report evidence.
+- Completion requires a terminal outcome (`finished`, `blocked`, `failed`, `cancelled`, or `askuserQuestion`) plus fresh verification evidence or an explicit validation gap.
+<!-- END ACTIVE AUTONOMY CORE -->