@jstn-sdk/ma 0.1.6 → 0.1.8

package/.codex/prompts/enforcement.md

@@ -54,6 +54,16 @@ The kernel may be minimal, but it must be strict. Extensions may vary, but they
 
 `https://gitmcp.io/docs` is fallback policy only. It is not a normal approved evidence source for unlocking `$build`.
 
+Approved discovery accelerators include `https://ossium.live/home`, `https://trendshift.io/`, `https://devhunt.org/`, `https://libraries.io/`, `https://openhub.net/`, and `https://www.opensourceprojects.dev/`.
+
+These discovery accelerators help find OSS candidates faster, but they are not by themselves VERIFIED evidence sources for unlocking `$build`.
+
+Canonical evidence order:
+1. If the upstream repo or official docs are already known, start there.
+2. Otherwise use approved discovery accelerators to generate or narrow candidates.
+3. Map the chosen candidate to an exact upstream repository.
+4. Verify against upstream repos and official docs before upgrading evidence status.
+
 ## Release truth rule
 
 Do not claim a channel is published unless the corresponding push, release creation, asset upload, or package publish actually succeeded.

package/README.md

@@ -18,9 +18,9 @@
 </div>
 
 > [!IMPORTANT]
-> Meta-Architect `v0.1.6` is a production-grade skills line.
+> Meta-Architect `v0.1.8` is a production-grade skills line.
 > It is not a lightweight demo branch.
-> From `v0.1.6` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
+> From `v0.1.8` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
 
 ## Overview
 
@@ -57,7 +57,7 @@ It adds:
   </tr>
   <tr>
     <td><strong>Release line</strong></td>
-    <td><code>v0.1.6</code></td>
+    <td><code>v0.1.8</code></td>
   </tr>
   <tr>
     <td><strong>License</strong></td>
@@ -230,7 +230,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.6
+8. Delivery plan for v0.1.8
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -256,10 +256,16 @@ See [example/usage-workflow.md](./example/usage-workflow.md) for the full prompt
 If you are working from a repository directly and need scaffolded local support files, use:
 
 ```bash
+ma bootstrap
+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
+- use `ma doctor` later when you want a check-only readiness report without changing files
+
 Expected output for `ma setup`:
 
 ```text
@@ -298,9 +304,33 @@ Recommended starter endpoints:
 - `https://gitmcp.io/dzharii/awesome-typescript`
 - `https://gitmcp.io/sbilly/awesome-security`
 
+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`
+
+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
 
@@ -384,10 +414,22 @@ What `ma setup` and `ma init` do:
 - 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
+- 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
 - use `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` inside the Codex session
+- 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
 
@@ -563,7 +605,7 @@ Release automation:
 | [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.6.md) | QA evidence for the `v0.1.6` line |
+| [Release Readiness](./docs/qa/release-readiness-0.1.8.md) | QA evidence for the `v0.1.8` line |
 
 ## Release Hygiene
 

package/bin/ma.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { runBootstrap, runDoctor } from "../src/bootstrap.js";
 import {
   evaluateBuildGate,
   formatBuildBlockers,
@@ -36,6 +37,8 @@ import { syncStatusUpdates } from "../src/state-sync.js";
 function printUsage() {
   console.error("Secondary helper commands:");
   console.error("  ma");
+  console.error("  ma bootstrap");
+  console.error("  ma doctor");
   console.error("  ma setup");
   console.error("  ma init");
   console.error('  ma idea "..."');
@@ -220,6 +223,18 @@ async function main() {
     return;
   }
 
+  if (command === "bootstrap") {
+    const outcome = await runBootstrap();
+    process.exitCode = outcome.result === "BLOCKED" ? 1 : 0;
+    return;
+  }
+
+  if (command === "doctor") {
+    const outcome = await runDoctor();
+    process.exitCode = outcome.result === "BLOCKED" ? 1 : 0;
+    return;
+  }
+
   if (command === "init") {
     const created = await runInit();
     console.log("meta-architect init");

package/docs/README.md

@@ -17,7 +17,7 @@ Meta-Architect documentation is organized by operator task.
 
 ## QA and readiness
 
-- [Release Readiness 0.1.6](./qa/release-readiness-0.1.6.md)
+- [Release Readiness 0.1.8](./qa/release-readiness-0.1.8.md)
 
 ## Repo structure references
 

package/docs/getting-started.md

@@ -74,7 +74,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.6
+8. Delivery plan for v0.1.8
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -181,6 +181,16 @@ Easy rule:
 - they prepare context, specs, plans, evidence, and runbook files
 - they do not automatically run the skill workflow
 
+`ma bootstrap` is the lazy-user path:
+- it checks whether `codex` is callable
+- it repairs installed skills and support-bundle assets when possible
+- it runs local scaffold setup
+- it reports `READY`, `READY_WITH_WARNINGS`, or `BLOCKED`
+
+`ma doctor` is the check-only path:
+- it runs the same environment checks without changing files
+- it prints the current readiness state and exact next step
+
 `ma sdk-path` prints the installed packaged support-bundle root for relevant files such as prompts, MCP files, sprint files, scripts, plugin metadata, and templates.
 
 ## 5. Configure MCP / GitMCP
@@ -205,6 +215,21 @@ Recommended first set:
 - `dzharii/awesome-typescript`
 - `sbilly/awesome-security`
 
+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
+- use `https://trendshift.io/` to spot repositories with rising engagement and topic momentum
+- use `https://devhunt.org/` to discover newly launched developer tools
+- use `https://libraries.io/` to inspect package/dependency metadata, while remembering its public data is scraped and not validated/curated for accuracy
+- use `https://openhub.net/` to inspect project activity, contributor, popularity, and comparison signals
+- 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
+
+Canonical `$sage` order:
+- known upstream repo/docs first
+- discovery accelerators second
+- exact GitMCP repo mapping third
+- upstream repo + official-doc verification last
+
 See [docs/mcp-setup.md](./mcp-setup.md) for endpoint policy and evidence semantics.
 
 ## 6. Secondary helper flow

package/docs/mcp-setup.md

@@ -1,5 +1,48 @@
 # MCP / GitMCP Setup
 
-1. Add repo-specific GitMCP endpoints in `mcp/servers.json`.
-2. Confirm categories in `mcp/collections.json`.
-3. Use `https://gitmcp.io/docs` only when no approved exact endpoint exists.
+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/qa/{release-readiness-0.1.6.md → release-readiness-0.1.8.md}

@@ -1,25 +1,25 @@
-# Release Readiness 0.1.6
+# Release Readiness 0.1.8
 
 ## Production bar
 
-`v0.1.6` is treated as production only when:
+`v0.1.8` 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.6`
+- release docs, package metadata, and workflows all agree on `0.1.8`
 
 Target release state:
-- npm package: `@jstn-sdk/ma@0.1.6`
+- npm package: `@jstn-sdk/ma@0.1.8`
 - npm registry state: pending publish
-- publishability note: `0.1.5` is already published, so `0.1.6` is the next publishable package line
-- git tag: `v0.1.6`
-- GitHub release: pending publish for `v0.1.6`
+- publishability note: `0.1.7` is already published, so `0.1.8` is the next publishable package line
+- git tag: `v0.1.8`
+- GitHub release: pending publish for `v0.1.8`
 
 ## Production checklist
 
 - skills-first product identity: PASS
 - package/plugin identity aligned to `@jstn-sdk/ma`: PASS
-- version/tag alignment `0.1.6` / `v0.1.6`: PASS
+- version/tag alignment `0.1.8` / `v0.1.8`: PASS
 - install/uninstall docs aligned: PASS
 - onboarding is concise and sequential: PASS
 - helper command documented as secondary: PASS

package/docs/release-spec.md

@@ -1,13 +1,13 @@
-# v0.1.6 Requirements & Rules
+# v0.1.8 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.6` is production only when:
+Meta-Architect `v0.1.8` 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
 
-## What `v0.1.6` must have
+## What `v0.1.8` must have
 
 ### 1. Canonical package/runtime path
 
@@ -49,11 +49,11 @@ Canonical state files:
 
 ### 4. Required release evidence
 
-- `package.json` version `0.1.6`
-- git tag `v0.1.6`
+- `package.json` version `0.1.8`
+- git tag `v0.1.8`
 - `RELEASE.md`
 - `CHANGELOG.md`
-- `docs/qa/release-readiness-0.1.6.md`
+- `docs/qa/release-readiness-0.1.8.md`
 - green `npm run release:check`
 
 ### 5. Dist-tag discipline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jstn-sdk/ma",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Codex-native skills system for architecture, evidence, review, and gated build guidance.",
   "license": "MIT",
   "author": "JustineDevs",

package/plugins/meta-architect/.app.json

@@ -1,7 +1,7 @@
 {
   "name": "meta-architect",
   "displayName": "Meta-Architect",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Programmatic architecture and verified engineering skills for Codex-native workflows.",
   "entry": "./README.md",
   "skillsDir": "./skills"

package/plugins/meta-architect/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Skills-first workflow layer for Codex with architecture, evidence, review, and gated build guidance.",
   "author": {
     "name": "JustineDevs",

package/plugins/meta-architect/.mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "collections": [
     "sindresorhus/awesome",
     "dzharii/awesome-typescript",

package/plugins/meta-architect/README.md

@@ -105,7 +105,7 @@ When consuming the plugin:
 The plugin version should track the release scope of the core repo.
 
 For this repository:
-- plugin scope is aligned to Meta-Architect `v0.1.6`
+- plugin scope is aligned to Meta-Architect `v0.1.8`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.

package/plugins/meta-architect/skills/meta-architect/SKILL.md

@@ -22,6 +22,8 @@ Run the full Meta-Architect workflow inside Codex. Use this skill when the user
 
 - Stay inside Codex unless the user explicitly asks for repo-local helper commands.
 - Keep the workflow architecture-first. Do not jump into code before the architecture and review lanes are grounded.
+- Use approved discovery accelerators such as Ossium, Trendshift, Dev Hunt, Libraries.io, Open Hub, and Open-source Projects when you need faster OSS candidate discovery, then validate any promising project through upstream repos and official docs.
+- Keep the `$sage` order explicit: known upstream sources first, discovery accelerators second, exact repo mapping third, approval only after upstream verification.
 - Prefer official docs, upstream repos, and repo-configured GitMCP sources when validating tooling choices.
 - End each lane with a clear result shape: decision, evidence, blockers, and exact next trigger.
 

package/plugins/meta-architect/skills/sage/SKILL.md

@@ -19,6 +19,19 @@ Produce:
 
 ## Rules
 
+- Follow this order:
+  - use known upstream repos and official docs first when they already exist
+  - use discovery accelerators to find or narrow candidates
+  - map the selected candidate back to an exact upstream repo
+  - verify against upstream repos and official docs before approving it
+- Use approved discovery accelerators when you need faster OSS candidate discovery:
+  - Ossium (`https://ossium.live/home`) for trending, curated, YC-backed, and GSoC-linked OSS discovery
+  - Trendshift (`https://trendshift.io/`) for rising GitHub engagement and topic momentum
+  - Dev Hunt (`https://devhunt.org/`) for newly launched developer tools
+  - Libraries.io (`https://libraries.io/`) for package/dependency metadata, with caution because its public data is scraped and not validated/curated for accuracy
+  - Open Hub (`https://openhub.net/`) for project activity, contributor, and comparison signals
+  - Open-source Projects (`https://www.opensourceprojects.dev/`) for curated OSS discovery and detailed project writeups
 - Do not invent package capabilities or maturity claims.
 - Prefer primary sources over summaries when validating technical details.
+- Do not treat discovery listings alone as VERIFIED evidence; promote candidates to upstream repos and official docs before approving them.
 - If the evidence is weak or contradictory, say so clearly and keep the recommendation conditional.

package/skills/meta-architect/SKILL.md

@@ -22,6 +22,8 @@ Run the full Meta-Architect workflow inside Codex. Use this skill when the user
 
 - Stay inside Codex unless the user explicitly asks for repo-local helper commands.
 - Keep the workflow architecture-first. Do not jump into code before the architecture and review lanes are grounded.
+- Use approved discovery accelerators such as Ossium, Trendshift, Dev Hunt, Libraries.io, Open Hub, and Open-source Projects when you need faster OSS candidate discovery, then validate any promising project through upstream repos and official docs.
+- Keep the `$sage` order explicit: known upstream sources first, discovery accelerators second, exact repo mapping third, approval only after upstream verification.
 - Prefer official docs, upstream repos, and repo-configured GitMCP sources when validating tooling choices.
 - End each lane with a clear result shape: decision, evidence, blockers, and exact next trigger.
 

package/skills/sage/SKILL.md

@@ -19,6 +19,19 @@ Produce:
 
 ## Rules
 
+- Follow this order:
+  - use known upstream repos and official docs first when they already exist
+  - use discovery accelerators to find or narrow candidates
+  - map the selected candidate back to an exact upstream repo
+  - verify against upstream repos and official docs before approving it
+- Use approved discovery accelerators when you need faster OSS candidate discovery:
+  - Ossium (`https://ossium.live/home`) for trending, curated, YC-backed, and GSoC-linked OSS discovery
+  - Trendshift (`https://trendshift.io/`) for rising GitHub engagement and topic momentum
+  - Dev Hunt (`https://devhunt.org/`) for newly launched developer tools
+  - Libraries.io (`https://libraries.io/`) for package/dependency metadata, with caution because its public data is scraped and not validated/curated for accuracy
+  - Open Hub (`https://openhub.net/`) for project activity, contributor, and comparison signals
+  - Open-source Projects (`https://www.opensourceprojects.dev/`) for curated OSS discovery and detailed project writeups
 - Do not invent package capabilities or maturity claims.
 - Prefer primary sources over summaries when validating technical details.
+- Do not treat discovery listings alone as VERIFIED evidence; promote candidates to upstream repos and official docs before approving them.
 - If the evidence is weak or contradictory, say so clearly and keep the recommendation conditional.

package/src/bootstrap.js

@@ -0,0 +1,313 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { loadMcpServers } from "./mcp-config.js";
+import { getRepoRoot, getRuntimeWritePath } from "./paths.js";
+import {
+  areSkillsInstalled,
+  ensureSkillsInstalled,
+  ensureSupportBundleInstalled,
+  getSkillInstallRoot,
+  getSupportBundleRoot,
+  isSupportBundleInstalled,
+} from "./skill-installer.js";
+import { runInit } from "./skills.js";
+
+function makeStatus(kind, label, detail = "") {
+  return { kind, label, detail };
+}
+
+function resolveCodexCommand() {
+  return process.env.MA_CODEX_BIN ?? "codex";
+}
+
+function runCommand(command, args) {
+  const isNodeScript = [".js", ".mjs", ".cjs"].includes(path.extname(command));
+  const finalCommand = isNodeScript ? process.execPath : command;
+  const finalArgs = isNodeScript ? [command, ...args] : args;
+  return spawnSync(finalCommand, finalArgs, { encoding: "utf8" });
+}
+
+function inspectCodex() {
+  const command = resolveCodexCommand();
+  const result = runCommand(command, ["--version"]);
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message ?? result.stderr.trim() ?? result.stdout.trim();
+    return {
+      ok: false,
+      command,
+      detail: detail || "Codex command failed",
+      version: "",
+    };
+  }
+
+  return {
+    ok: true,
+    command,
+    detail: "",
+    version: result.stdout.trim(),
+  };
+}
+
+function listCodexPaths() {
+  const result = spawnSync("which", ["-a", "codex"], { encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    return [];
+  }
+
+  return result.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function isWindowsPathInWsl(value) {
+  return value.startsWith("/mnt/") && value.includes("/AppData/Roaming/npm/");
+}
+
+async function writeCodexWrapper() {
+  const wrapperDir = path.join(os.homedir(), ".local", "bin");
+  const wrapperPath = path.join(wrapperDir, "codex");
+  const content = `#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v node >/dev/null 2>&1; then
+  NODE_BIN="$(command -v node)"
+  NODE_DIR="$(dirname "$NODE_BIN")"
+  if [ -x "$NODE_DIR/codex" ] && [ "$NODE_DIR/codex" != "$0" ]; then
+    exec "$NODE_DIR/codex" "$@"
+  fi
+fi
+
+while IFS= read -r candidate; do
+  [ -n "$candidate" ] || continue
+  if [ "$candidate" = "$0" ]; then
+    continue
+  fi
+  case "$candidate" in
+    /mnt/*) continue ;;
+  esac
+  exec "$candidate" "$@"
+done < <(which -a codex 2>/dev/null || true)
+
+echo "Unable to locate a Linux Codex binary. Reinstall with: npm install -g @openai/codex@latest" >&2
+exit 1
+  `;
+
+  await fs.mkdir(wrapperDir, { recursive: true });
+  await fs.writeFile(wrapperPath, content, { mode: 0o755 });
+  await fs.chmod(wrapperPath, 0o755);
+  const pathEntries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  if (!pathEntries.includes(wrapperDir)) {
+    process.env.PATH = [wrapperDir, ...pathEntries].join(path.delimiter);
+  }
+  return wrapperPath;
+}
+
+async function inspectCodexResolution({ fix }) {
+  if (process.platform !== "linux") {
+    return null;
+  }
+
+  const paths = listCodexPaths();
+  if (paths.length === 0) {
+    return null;
+  }
+
+  const first = paths[0];
+  const linuxAlternative = paths.find((candidate) => !isWindowsPathInWsl(candidate));
+  if (!isWindowsPathInWsl(first) || !linuxAlternative) {
+    return null;
+  }
+
+  if (!fix) {
+    return makeStatus(
+      "WARN",
+      "codex path points at a Windows npm install inside WSL",
+      `Preferred path is ${first}; Linux alternative exists at ${linuxAlternative}`,
+    );
+  }
+
+  const wrapperPath = await writeCodexWrapper();
+  return makeStatus(
+    "FIXED",
+    "codex path will prefer a Linux wrapper inside WSL",
+    `Installed wrapper at ${wrapperPath}`,
+  );
+}
+
+async function inspectLocalScaffold() {
+  const requiredFiles = [
+    getRuntimeWritePath("decisions.json"),
+    getRuntimeWritePath("release.json"),
+    path.join(getRepoRoot(), "mcp", "servers.json"),
+  ];
+
+  for (const file of requiredFiles) {
+    try {
+      await fs.access(file);
+    } catch {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+async function inspectMcpState() {
+  try {
+    const servers = await loadMcpServers();
+    if (servers.servers.length === 0) {
+      return makeStatus(
+        "WARN",
+        "mcp/servers.json exists but contains no approved repo-backed sources",
+        "Add exact upstream GitMCP repo endpoints before claiming VERIFIED evidence.",
+      );
+    }
+
+    return makeStatus(
+      "OK",
+      "mcp/servers.json has approved starter sources",
+      `${servers.servers.length} configured source(s)`,
+    );
+  } catch (error) {
+    return makeStatus("WARN", "mcp/servers.json is not ready for evidence binding", error.message);
+  }
+}
+
+async function runEnvironmentFlow({ fix }) {
+  const statuses = [];
+
+  const codexResolution = await inspectCodexResolution({ fix });
+  if (codexResolution) {
+    statuses.push(codexResolution);
+  }
+
+  const codex = inspectCodex();
+  if (codex.ok) {
+    statuses.push(makeStatus("OK", "codex command is available", codex.version));
+  } else {
+    statuses.push(
+      makeStatus(
+        "BLOCKED",
+        "codex command is not usable",
+        "Install or repair Codex with: npm install -g @openai/codex@latest",
+      ),
+    );
+  }
+
+  const skillInstallRoot = getSkillInstallRoot();
+  if (fix) {
+    const result = await ensureSkillsInstalled();
+    statuses.push(
+      makeStatus(
+        result.installed.length > 0 ? "FIXED" : "OK",
+        "Codex skills are installed",
+        skillInstallRoot,
+      ),
+    );
+  } else {
+    statuses.push(
+      makeStatus(
+        (await areSkillsInstalled()) ? "OK" : "WARN",
+        "Codex skills install state",
+        skillInstallRoot,
+      ),
+    );
+  }
+
+  const supportBundleRoot = getSupportBundleRoot();
+  if (fix) {
+    const result = await ensureSupportBundleInstalled();
+    statuses.push(
+      makeStatus(
+        result.installed.length > 0 ? "FIXED" : "OK",
+        "support bundle is installed",
+        supportBundleRoot,
+      ),
+    );
+  } else {
+    statuses.push(
+      makeStatus(
+        (await isSupportBundleInstalled()) ? "OK" : "WARN",
+        "support bundle install state",
+        supportBundleRoot,
+      ),
+    );
+  }
+
+  if (fix) {
+    await runInit();
+    statuses.push(
+      makeStatus(
+        "FIXED",
+        "local Meta-Architect scaffold is ready",
+        path.join(getRepoRoot(), ".ma"),
+      ),
+    );
+  } else {
+    statuses.push(
+      makeStatus(
+        (await inspectLocalScaffold()) ? "OK" : "WARN",
+        "local Meta-Architect scaffold state",
+        path.join(getRepoRoot(), ".ma"),
+      ),
+    );
+  }
+
+  statuses.push(await inspectMcpState());
+  return statuses;
+}
+
+function summarizeStatuses(statuses) {
+  const hasBlocked = statuses.some((status) => status.kind === "BLOCKED");
+  const hasWarn = statuses.some((status) => status.kind === "WARN");
+  if (hasBlocked) {
+    return "BLOCKED";
+  }
+  if (hasWarn) {
+    return "READY_WITH_WARNINGS";
+  }
+  return "READY";
+}
+
+function printStatuses(title, statuses) {
+  console.log(title);
+  console.log("=".repeat(title.length));
+  for (const status of statuses) {
+    const label = status.kind.padEnd(7, " ");
+    if (status.detail) {
+      console.log(`${label} ${status.label}: ${status.detail}`);
+    } else {
+      console.log(`${label} ${status.label}`);
+    }
+  }
+  const result = summarizeStatuses(statuses);
+  console.log();
+  console.log(`Result: ${result}`);
+  if (result === "BLOCKED") {
+    console.log("Next: install or repair blocked prerequisites, then rerun `ma bootstrap`.");
+  } else if (result === "READY_WITH_WARNINGS") {
+    console.log("Next: review warnings, then start Codex or run `ma run '$maestro'`.");
+  } else {
+    console.log("Next: start Codex or run `ma run '$maestro'`.");
+  }
+  return result;
+}
+
+export async function runDoctor() {
+  const statuses = await runEnvironmentFlow({ fix: false });
+  return {
+    statuses,
+    result: printStatuses("Meta-Architect Doctor", statuses),
+  };
+}
+
+export async function runBootstrap() {
+  const statuses = await runEnvironmentFlow({ fix: true });
+  return {
+    statuses,
+    result: printStatuses("Meta-Architect Bootstrap", statuses),
+  };
+}

package/src/launcher.js

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import path from "node:path";
 
 const nativeCommands = new Set([
+  "bootstrap",
+  "doctor",
   "setup",
   "init",
   "idea",

package/src/mcp-live-client.js

@@ -38,7 +38,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.6",
+        version: "0.1.8",
       },
     });
 

package/src/skills.js

@@ -508,8 +508,8 @@ export async function runInit() {
       path.join(getRepoRoot(), "docs", "release-spec.md"),
     ],
     [
-      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.6.md"),
-      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.6.md"),
+      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.8.md"),
+      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.8.md"),
     ],
   ];
 

package/templates/AGENTS.md

@@ -71,10 +71,27 @@ If any required field is missing, red, or unverified, the workflow should stop a
 
 Major technology recommendations must be supported by evidence from configured MCP/GitMCP sources. Do not invent fake repositories, fake endpoints, or unsupported claims.
 
+Approved discovery accelerators include:
+- Ossium (`https://ossium.live/home`) for trending OSS, curated repos, YC-backed repos, GSoC orgs, and contribution leads
+- Trendshift (`https://trendshift.io/`) for rising GitHub engagement and topic momentum
+- Dev Hunt (`https://devhunt.org/`) for newly launched developer tools
+- Libraries.io (`https://libraries.io/`) for package/dependency metadata, with caution because its public data is scraped and not validated/curated for accuracy
+- Open Hub (`https://openhub.net/`) for project activity, contributor, popularity, and comparison signals
+- Open-source Projects (`https://www.opensourceprojects.dev/`) for curated OSS discovery and detailed project writeups
+
+These discovery accelerators do not replace upstream repo evidence or official docs for approval decisions.
+
+Canonical evidence order:
+- prefer known upstream repos and official docs first
+- use discovery accelerators to find or narrow candidates
+- map selected candidates back to exact upstream repositories
+- approve only after upstream repo and official-doc verification
+
 ### Exact endpoint rule
 
 - Prefer repo-specific `https://gitmcp.io/{owner}/{repo}` endpoints
 - Treat `https://gitmcp.io/docs` as fallback policy only, not a normal approved evidence source for build-unlocking decisions
+- Treat discovery accelerators as discovery-only until a candidate is mapped back to an exact upstream repository and validated through approved evidence paths
 
 ## Logging rule