@jstn-sdk/ma 0.1.5 → 0.1.7

package/docs/mcp-setup.md

@@ -1,136 +1,48 @@
 # MCP / GitMCP Setup
 
-Meta-Architect uses MCP as the protocol layer and GitMCP as the remote evidence surface for curated OSS repositories.
-
-## Files that matter
-
-- `mcp/servers.json`
-- `mcp/collections.json`
-- `mcp/fallback.json`
-
-These are committed product config files, not hidden runtime state.
-
-## How server mappings work
-
-### `mcp/servers.json`
-
-Defines the approved exact GitMCP-backed repositories the runtime may probe.
-
-Each entry should include:
-- `category`
-- `repo`
-- `endpoint`
-
-Example:
-
-```json
-{
-  "category": "security",
-  "repo": "sbilly/awesome-security",
-  "endpoint": "https://gitmcp.io/sbilly/awesome-security"
-}
-```
-
-### `mcp/collections.json`
-
-Defines the committed lane-to-category policy:
-- which categories belong to `arch`
-- which belong to `sage`
-- which belong to `vet`
-
-The current runtime probes `mcp/servers.json` directly, while `mcp/collections.json` remains the committed contract for how category routing should be understood and evolved.
-
-### `mcp/fallback.json`
-
-Defines the documented fallback rule for:
-- `https://gitmcp.io/docs`
-
-Fallback is a policy declaration, not permission to skip exact endpoints when those are already known.
-
-## Endpoint strategy
-
-Preferred rule:
-- use repo-specific `https://gitmcp.io/{owner}/{repo}` endpoints
-- avoid generic discovery when an exact approved repo is already known
-
-This keeps recommendations scoped and auditable.
-
-## GitMCP collection examples
-
-Useful committed examples:
-- `sindresorhus/awesome`
-- `dzharii/awesome-typescript`
-- `rust-unofficial/awesome-rust`
-- `sbilly/awesome-security`
-- `awesome-selfhosted/awesome-selfhosted`
-
-## How `$sage` uses live evidence
-
-Current `$sage` behavior:
-1. requires `architecture_status = APPROVED`
-2. reads `mcp/servers.json`
-3. validates endpoint shape
-4. derives the query from the latest architecture summary
-5. opens a live GitMCP SSE connection when live probing is enabled
-6. negotiates the MCP message endpoint
-7. runs `tools/list`
-8. runs one repo-specific tool call
-9. writes probe metadata into `.omx/evidence/sources.json`
-
-This is enough to provide real runtime evidence for the first configured approved source. It is not a full multi-source reasoning engine yet.
-
-## VERIFIED vs PARTIAL vs MISSING
-
-### `VERIFIED`
-- at least one approved endpoint is configured
-- a real live probe succeeds
-- usable evidence is written
-
-### `PARTIAL`
-- configured evidence exists
-- but live proof is incomplete, disabled, or degraded
-
-### `MISSING`
-- no valid approved source exists
-
-Do not silently mark evidence as verified when the live source did not succeed.
-
-## What to do when MCP is unavailable
-
-If MCP or GitMCP is unavailable:
-- keep evidence partial or missing
-- record the failure explicitly
-- do not fabricate evidence
-- fix the endpoint or network condition first
-- rerun `$sage`
-
-## How to keep committed MCP config honest
-
-- commit real or intentionally documented example endpoints only
-- do not leave fake placeholders in production config
-- update this file if category policy changes
-- treat endpoint drift as a release-sensitive change
-
-## Example setup workflow
-
-1. edit `mcp/servers.json`
-2. confirm categories in `mcp/collections.json`
-3. inspect fallback policy in `mcp/fallback.json`
-4. ensure `$arch` already approved the architecture
-5. run:
-
-```bash
-ma run '$sage'
-```
-
-6. inspect:
-- `.omx/evidence/sources.json`
-- `.omx/decisions.json`
-- `.omx/release.json`
-
-## Related surfaces
-
-- [README.md](../README.md)
-- [docs/skills.md](./skills.md)
-- [docs/release-spec.md](./release-spec.md)
-- [plugins/meta-architect/README.md](../plugins/meta-architect/README.md)
+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.
+
+## Discovery vs verification
+
+Canonical `$sage` order:
+
+1. If the upstream repository or official docs are already known, start there first.
+2. If not, use approved discovery accelerators to build a candidate set quickly.
+3. Convert promising candidates into exact upstream repository mappings in `mcp/servers.json`.
+4. Verify the choice against the upstream repo and official docs.
+5. Treat the result as `VERIFIED`, `PARTIAL`, or `UNVERIFIED` based on what was actually proven.
+
+The following external discovery surfaces are part of the Meta-Architect discovery standard:
+
+- `https://ossium.live/home`
+  - use for trending OSS, curated repositories, YC-backed repos, GSoC orgs, and contribution leads
+- `https://trendshift.io/`
+  - use for rising GitHub repository engagement, topic-driven exploration, and trend signals
+- `https://devhunt.org/`
+  - use for newly launched developer tools and discovery of current dev-tool products
+- `https://libraries.io/`
+  - use for package, ecosystem, license, and dependency metadata
+  - caution: Libraries.io says its public data is scraped and "not validated, corrected, or curated for accuracy"
+- `https://openhub.net/`
+  - use for project activity, contributor, popularity, and comparative OSS project signals
+- `https://www.opensourceprojects.dev/`
+  - use for curated open-source project discovery, detailed project writeups, and higher-signal project scouting
+
+Use it for:
+- discovering candidate repositories
+- spotting trending or actively curated OSS
+- finding contribution-friendly projects and issue flows
+- finding YC-linked or GSoC-linked OSS leads faster
+- checking package-ecosystem metadata, maintenance signals, and dependency context
+- checking project activity and contributor/comparison signals
+- checking curated project writeups and hand-picked OSS recommendations
+
+Do not treat any of these discovery surfaces alone as VERIFIED build-unlocking evidence.
+
+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`

package/docs/onboarding.md

@@ -1,35 +1,65 @@
 # Onboarding
 
-This file is the short operator entrypoint for someone who just opened the repo and needs to
-understand the Codex-native Meta-Architect runtime model.
+This is the shortest entrypoint for the real first-run Meta-Architect path.
 
-## First reading order
+## Read first
 
 1. `README.md`
 2. `docs/getting-started.md`
-3. `docs/release-spec.md`
-4. `docs/skills.md`
+3. `example/usage-workflow.md`
+4. `docs/release-spec.md`
 5. `docs/skills-publishing.md`
 
-## First commands
+## Canonical install and start
 
 ```bash
-npm i -g @openai/codex @jstn-sdk/ma
+# Install
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+
+# 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
+```
+
+## First runtime action
+
+Start with the structured `$arch` prompt from [example/usage-workflow.md](../example/usage-workflow.md):
+
+```text
+$arch I want to build: [PROJECT IDEA]
 ```
 
-Inside Codex, use the runtime tags directly:
-- `$arch`
+Then continue through:
 - `$sage`
 - `$flow`
 - `$vet`
 - `$vibe`
 - `$build`
 
+## Secondary helper path
+
+Only use this when you need local repo scaffolding or scripted validation:
+
+```bash
+ma setup
+ma
+ma idea "..."
+ma run '$arch'
+ma run '$sage'
+ma run '$flow'
+ma run '$vet'
+ma run '$vibe'
+ma run '$build'
+```
+
 ## First safety rules
 
-- Do not commit runtime `.omx` state.
+- Do not commit runtime `.ma` state.
 - Do not bypass gates by editing status files manually.
 - Do not assume a release channel succeeded without evidence.
 - Do not treat fallback MCP docs mode as normal verified evidence.
-- Do not present `ma setup` as the main daily workflow.

package/docs/qa/release-readiness-0.1.5.md

@@ -2,42 +2,62 @@
 
 ## Production bar
 
-`v0.1.5` is production only when:
-- the Codex-hosted runtime workflow is reliable end-to-end
-- the runtime/help/release contract is stable
-- package metadata, manifests, docs, workflows, and release artifacts all agree on `0.1.5`
-- provenance-capable publishing and post-publish verification are in place
-
-## Automated checks
-
-Release-critical verification command:
+`v0.1.5` is treated as production only when:
+- the package installs cleanly from the canonical public install command
+- the Codex-hosted runtime path works end to end
+- the helper flow remains valid for scripted verification
+- release docs, package metadata, and workflows all agree on `0.1.5`
+
+Target release state:
+- npm package: `@jstn-sdk/ma@0.1.5`
+- npm registry state: pending publish
+- publishability note: `0.1.4` is already published, so `0.1.5` is the next publishable package line
+- git tag: `v0.1.5`
+- GitHub release: pending publish for `v0.1.5`
+
+## Production checklist
+
+- skills-first product identity: PASS
+- package/plugin identity aligned to `@jstn-sdk/ma`: PASS
+- version/tag alignment `0.1.5` / `v0.1.5`: PASS
+- install/uninstall docs aligned: PASS
+- onboarding is concise and sequential: PASS
+- helper command documented as secondary: PASS
+- skills/prompts/manifests aligned: PASS
+- packaging includes required assets: PASS
+- tests pass: PASS
+- package dry-run passes: PASS
+- installed-package behavior passes: PASS
+- workflow/release/provenance docs aligned: PASS
+- no stale package names remain in tracked repo surfaces: PASS
+- no conflicting CLI-first product story remains in tracked product docs: PASS
+
+## Automated checks run
 
 ```bash
 npm run release:check
 ```
 
-This must cover:
-- manifest generation
+That must cover:
+- skills manifest generation
 - skill validation
-- skill tarball packaging
-- package metadata validation
-- release doc/version/tag alignment
-- workflow/provenance configuration validation
-- Biome checks
+- skill bundle packaging
+- repo checks
 - automated tests
 - npm package dry-run inspection
 
-## Additional checks
+## Manual/behavioral checks run
 
-Runtime posture:
+Canonical launch:
 
 ```bash
 ma --madmax --high
 ```
 
-Scripted helper path for repo-local validation:
+Helper-path validation:
 
 ```bash
+ma setup
 ma idea "Build a demo app"
 ma run '$arch'
 ma run '$sage'
@@ -48,30 +68,12 @@ ma status
 ma run '$build'
 ```
 
-Expected result:
-- all helper commands succeed in sequence
-- `$build` remains blocked until upstream gates are green
-- ready builds emit bounded `feature/*` branch suggestions
-
-## Provenance checklist
-
-- `.github/workflows/npm-publish.yml` uses GitHub Actions trusted publishing
-- workflow permissions include `contents: read` and `id-token: write`
-- publish command is `npm publish --provenance --access public`
-- post-publish workflow verifies the published package version on npm
-- post-publish workflow installs the published package in a clean directory and runs `npm audit signatures`
-
-## Release artifact checklist
-
-- `package.json` version is `0.1.5`
-- `package-lock.json` version is `0.1.5`
-- `CHANGELOG.md` contains `## v0.1.5`
-- `RELEASE.md` title is `# Meta-Architect v0.1.5`
-- `docs/release-spec.md` references `v0.1.5`
-- `dist/meta-architect-skills.tgz` exists and is non-empty
+Expected evidence:
+- `.ma/release.json` remains the source of truth
+- `.ma/decisions.json` records the helper-path activity
+- `$build` stays blocked until upstream gates are green, then becomes ready
 
-## Known limits
+## Known limitations
 
-- worktree execution remains operator-driven
-- merge and release policy is enforced by helper commands rather than raw git hooks
-- npm publish still requires the external trusted-publishing configuration on npm to be enabled for the repository
+- interactive Codex conversation quality depends on the installed Codex host
+- release publication still depends on npm ownership/authorization for the target package name

package/docs/qa/release-readiness-0.1.7.md

@@ -0,0 +1,79 @@
+# Release Readiness 0.1.7
+
+## Production bar
+
+`v0.1.7` is treated as production only when:
+- the package installs cleanly from the canonical public install command
+- the Codex-hosted runtime path works end to end
+- the helper flow remains valid for scripted verification
+- release docs, package metadata, and workflows all agree on `0.1.7`
+
+Target release state:
+- npm package: `@jstn-sdk/ma@0.1.7`
+- npm registry state: pending publish
+- publishability note: `0.1.6` is already published, so `0.1.7` is the next publishable package line
+- git tag: `v0.1.7`
+- GitHub release: pending publish for `v0.1.7`
+
+## Production checklist
+
+- skills-first product identity: PASS
+- package/plugin identity aligned to `@jstn-sdk/ma`: PASS
+- version/tag alignment `0.1.7` / `v0.1.7`: PASS
+- install/uninstall docs aligned: PASS
+- onboarding is concise and sequential: PASS
+- helper command documented as secondary: PASS
+- skills/prompts/manifests aligned: PASS
+- packaging includes required assets: PASS
+- tests pass: PASS
+- package dry-run passes: PASS
+- installed-package behavior passes: PASS
+- workflow/release/provenance docs aligned: PASS
+- no stale package names remain in tracked repo surfaces: PASS
+- no conflicting CLI-first product story remains in tracked product docs: PASS
+
+## Automated checks run
+
+```bash
+npm run release:check
+```
+
+That must cover:
+- skills manifest generation
+- skill validation
+- skill bundle packaging
+- repo checks
+- automated tests
+- npm package dry-run inspection
+
+## Manual/behavioral checks run
+
+Canonical launch:
+
+```bash
+ma --madmax --high
+```
+
+Helper-path validation:
+
+```bash
+ma setup
+ma idea "Build a demo app"
+ma run '$arch'
+ma run '$sage'
+ma run '$flow'
+ma run '$vet'
+ma run '$vibe'
+ma status
+ma run '$build'
+```
+
+Expected evidence:
+- `.ma/release.json` remains the source of truth
+- `.ma/decisions.json` records the helper-path activity
+- `$build` stays blocked until upstream gates are green, then becomes ready
+
+## Known limitations
+
+- interactive Codex conversation quality depends on the installed Codex host
+- release publication still depends on npm ownership/authorization for the target package name

package/docs/release-spec.md

@@ -1,115 +1,93 @@
-# v0.1.5 Requirements & Rules
+# v0.1.7 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.5` is production only when all of the following are true:
+Meta-Architect `v0.1.7` is production only when:
+1. the package/install surface works
+2. the in-session skill workflow from `$arch` through `$build` works
+3. the release evidence matches the actual package and git tag
 
-1. The Codex-hosted runtime workflow is reliable end-to-end.
-2. The public runtime, helper, and release contract is stable.
-3. There is documented release evidence for the exact version and tag.
+## What `v0.1.7` must have
 
-Production here means safe to recommend for real projects and expensive to break without a major version change.
+### 1. Canonical package/runtime path
 
-## What `v0.1.5` must have
-
-### 1. Runtime-first operation
-
-- `ma --madmax --high` launches the Codex-hosted Meta-Architect posture.
-- The primary operating surface inside Codex is:
+- install: `npm i -g @openai/codex@latest @jstn-sdk/ma@latest`
+- optional helper launch: `ma --madmax --high`
+- uninstall Meta-Architect only: `npm uninstall -g @jstn-sdk/ma`
+- uninstall Meta-Architect and Codex: `npm uninstall -g @jstn-sdk/ma @openai/codex`
+- runtime trigger surface:
   - `$arch`
   - `$sage`
   - `$flow`
   - `$vet`
   - `$vibe`
   - `$build`
-- Helper commands remain secondary:
-  - `ma status`
-  - `ma idea`
-  - `ma run ...`
-  - `ma merge`
-  - `ma release`
-  - `ma doctor`
-  - `ma setup`
-
-### 2. Gate and status rules
-
-Required status fields:
-- `idea_status`
-- `architecture_status`
-- `evidence_status`
-- `logic_status`
-- `security_status`
-- `experience_status`
-- `build_status`
-- `merge_status`
-- `release_status`
-
-Allowed values:
-- `idea_status`: `DRAFT`, `CLEAR`, `BLOCKED`
-- `architecture_status`: `DRAFT`, `REVIEWED`, `APPROVED`
-- `evidence_status`: `MISSING`, `PARTIAL`, `VERIFIED`
-- `logic_status`: `PENDING`, `GREEN`, `RED`
-- `security_status`: `PENDING`, `GREEN`, `RED`
-- `experience_status`: `PENDING`, `GREEN`, `RED`, `WAIVED`
-- `build_status`: `LOCKED`, `READY`, `RUNNING`, `DONE`
-- `merge_status`: `LOCKED`, `READY`, `MERGED_TO_DEVELOPMENT`
-- `release_status`: `LOCKED`, `READY`, `SHIPPED_TO_PROD`
-
-`$build` must stay locked unless:
-- `idea_status = CLEAR`
-- `architecture_status = APPROVED`
-- `evidence_status = VERIFIED`
-- `logic_status = GREEN`
-- `security_status = GREEN`
-- `experience_status ∈ { GREEN, WAIVED }`
-- `build_status ∈ { LOCKED, READY }`
-
-### 3. Branch and release policy
-
-- `feature/*` is bounded task work.
-- `development` is the integration branch.
-- `release/*` is optional stabilization.
-- `prod` is the production release branch.
-
-Rules:
-- feature work merges into `development`, never directly into `prod`
-- release evaluation is valid only from `development` or approved `release/*`
-- no release claim is true until tag, GitHub release, and npm publish all succeed
-
-### 4. Evidence and MCP rules
-
-- `$sage` must use approved GitMCP endpoints from `mcp/servers.json`.
-- Generic `https://gitmcp.io/docs` fallback remains policy-only and cannot silently unlock `$build`.
-- Evidence must be logged honestly as `VERIFIED`, `PARTIAL`, or `MISSING`.
-- Fake repos, fake endpoints, and silent evidence upgrades are prohibited.
-
-### 5. Release packaging and provenance
-
-Required release evidence:
-- matching package version and git tag (`v0.1.5` format)
-- `CHANGELOG.md` entry
-- `RELEASE.md` body
-- `docs/qa/release-readiness-0.1.5.md`
-- `dist/meta-architect-skills.tgz`
-- npm trusted publishing configuration
-- post-publish provenance verification
-
-### 6. Required docs
-
-- `README.md`
-- `docs/getting-started.md`
-- `docs/skills.md`
-- `docs/mcp-setup.md`
-- `docs/skills-publishing.md`
-- `docs/release-spec.md`
-- `docs/qa/release-readiness-0.1.5.md`
-
-## Production rule
-
-Meta-Architect `v0.1.5` is considered production-ready only if:
-- a Codex session launches through `ma --madmax --high`
-- the full `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` contract works with gate enforcement
-- package, docs, workflows, manifests, and release notes all agree on `v0.1.5`
-- the skill distribution surfaces validate and package from a clean checkout
-- the npm publish workflow is provenance-capable
-- post-publish verification checks are defined and enforced
+
+### 2. Secondary helper path
+
+Helper commands remain available for setup and scripted validation:
+- `ma setup`
+- `ma idea`
+- `ma run ...`
+- `ma status`
+- `ma merge`
+- `ma release`
+
+### 3. State and gate contract
+
+Canonical runtime namespace:
+- `.ma/`
+
+Canonical state files:
+- `.ma/decisions.json`
+- `.ma/release.json`
+- `.ma/evidence/*`
+- `.ma/context/*`
+- `.ma/specs/*`
+- `.ma/plans/*`
+- `.ma/runbook.md`
+
+### 4. Required release evidence
+
+- `package.json` version `0.1.7`
+- git tag `v0.1.7`
+- `RELEASE.md`
+- `CHANGELOG.md`
+- `docs/qa/release-readiness-0.1.7.md`
+- green `npm run release:check`
+
+### 5. Dist-tag discipline
+
+- stable versions such as `0.1.2` publish to npm `latest`
+- prerelease versions such as `0.2.0-beta.1` must publish with explicit tags such as `beta`
+- recommended alternate lanes are `next`, `beta`, and `canary`
+- prerelease publication must use `npm publish --tag <lane>`
+- stable publication keeps scoped public access and provenance enabled
+
+### 6. Canonical bump and publish flow
+
+1. Run `npm version <version> --no-git-tag-version`
+2. Update `CHANGELOG.md`
+3. Update `RELEASE.md`
+4. Update `docs/qa/release-readiness-<version>.md`
+5. Run `npm run release:verify`
+6. Run `npm run release:check`
+7. Create and push tag `v<version>`
+8. Preferred publish path: publish from `.github/workflows/npm-publish.yml` on a supported cloud runner so provenance can be generated
+9. 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>`
+10. Verify dist-tags with `npm view @jstn-sdk/ma version dist-tags time --json`
+
+### 6.1 Release automation
+
+- `npm run release:sync` updates the active release line when watched release-relevant files changed
+- `npm run release:advance` force-bumps the next patch line after a completed release
+- `.github/workflows/release-sync.yml` automates the sync path on `main`
+- `.github/workflows/release-advance.yml` advances the repo to the next patch line after a published release
+
+### 7. Provenance rule
+
+- `npm publish --provenance` is valid only from a supported cloud CI/CD provider
+- local shell publishes are expected to fail with `Automatic provenance generation not supported for provider: null`
+- use the repository publish workflow when provenance is part of the release bar