baller-maester 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-21
+
+### Fixed
+- **Docs and CLI strings now use the correct npm package name.** Every `npx maester ...` invocation has been replaced with `npx baller-maester ...` (or `npx -y baller-maester ...` for automation contexts). `npx` resolves by npm package name and this project publishes as `baller-maester`, so the old form would have failed at the registry. Touches the README, CHANGELOG, every `gspec/` document that named the command, both skill-template content files (freshness-awareness and connector-policy-fallback), the `maester init` outro, the missing-config error messages in the config loader, and the auto-generated `citadel.yaml` / `maester.yaml` header comments.
+- **Grand Maester `PreToolUse` hook command is now actually invokable.** The `.claude/settings.json` block installed by `maester skill install` previously embedded `npx maester skill runtime preread`, which would fail npm-side resolution. Updated to `npx -y baller-maester skill runtime preread` (matching the existing MCP-registration convention). The `-y` flag skips npx's first-run confirmation so the hook does not stall Claude Code's tool-call flow.
+- **Stale docstrings on the MCP registration writers** for Claude Code and Codex CLI claimed the entry embedded `process.argv[1]` rather than `npx maester`; the code has actually emitted `npx -y baller-maester mcp` since 0.4.0. Rewrote both docstrings to match reality.
+
 ## [0.4.0] - 2026-05-21
 
 ### Added
@@ -56,5 +63,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Sync orchestration consolidated into a single `src/core/sources/fetcher.ts` (replacing the previously planned per-kind modules). The fetcher branches internally on whether the source declares an `includes` list.
-- **Repo-root detection is now always the current working directory.** `npx maester` (and every subcommand) treats `process.cwd()` as the root unconditionally — the old walk-upward-for-`.git`/`package.json` behavior is removed. `citadel.yaml` and `maester.yaml` always land in the directory where you typed the command, never in an ancestor. An existing config file in an ancestor directory is invisible to the cwd model.
+- **Repo-root detection is now always the current working directory.** `npx baller-maester` (and every subcommand) treats `process.cwd()` as the root unconditionally — the old walk-upward-for-`.git`/`package.json` behavior is removed. `citadel.yaml` and `maester.yaml` always land in the directory where you typed the command, never in an ancestor. An existing config file in an ancestor directory is invisible to the cwd model.
 - Top-level `baseDir` field on `citadel.yaml` (optional). When set, every source whose `destination` is unset is surfaced at `<baseDir>/<source-name>/` instead of `citadel/<source-name>/`. Per-source `destination` overrides always win. Omitting `baseDir` is identical to today's behavior — fully backward compatible. The citadel-init walkthrough prompts for it with `citadel` pre-filled and omits the field from the generated YAML when the default is accepted.

package/README.md

@@ -21,7 +21,7 @@ A directory can hold one role, the other, or both. There is at most one of each
 
 ### Where do the files land?
 
-**Every maester command uses the current working directory as the root.** When you run `npx maester init` from a directory, `citadel.yaml` is created in that exact directory — never in an ancestor. The same goes for `npx maester publish` (writes `maester.yaml` here), `npx maester sync` (reads `citadel.yaml` from here), and the interactive menu (`npx maester`).
+**Every maester command uses the current working directory as the root.** When you run `npx baller-maester init` from a directory, `citadel.yaml` is created in that exact directory — never in an ancestor. The same goes for `npx baller-maester publish` (writes `maester.yaml` here), `npx baller-maester sync` (reads `citadel.yaml` from here), and the interactive menu (`npx baller-maester`).
 
 If you run a maester command from the wrong directory, `cd` to the intended directory and re-run. The CLI does not walk upward to find a project root, so a stray `.git/` or `package.json` in a parent directory will not pull configuration files away from where you typed the command.
 
@@ -30,15 +30,15 @@ If you run a maester command from the wrong directory, `cd` to the intended dire
 In the directory you want to populate with aggregated knowledge:
 
 ```sh
-npx maester              # interactive menu (uses cwd as root)
-npx maester init         # citadel walkthrough — creates ./citadel.yaml
-npx maester sync         # fetch all configured sources — reads ./citadel.yaml
+npx baller-maester              # interactive menu (uses cwd as root)
+npx baller-maester init         # citadel walkthrough — creates ./citadel.yaml
+npx baller-maester sync         # fetch all configured sources — reads ./citadel.yaml
 ```
 
 In a directory that *publishes* docs to other citadels:
 
 ```sh
-npx maester publish      # maester manifest walkthrough — creates ./maester.yaml
+npx baller-maester publish      # maester manifest walkthrough — creates ./maester.yaml
 ```
 
 ## Pulling from sources you don't own
@@ -67,7 +67,7 @@ sources:
     description: Upstream React documentation snapshot.
 ```
 
-`npx maester sync` processes every source in one pass. The trade-off for the includes-driven mode: when the remote repo restructures, the citadel's `includes` may need to be updated. Sync prints a warning when an includes-driven source resolves to zero files so drift is visible.
+`npx baller-maester sync` processes every source in one pass. The trade-off for the includes-driven mode: when the remote repo restructures, the citadel's `includes` may need to be updated. Sync prints a warning when an includes-driven source resolves to zero files so drift is visible.
 
 ## Prerequisites
 

package/dist/cli/main.js

@@ -995,7 +995,7 @@ async function loadCitadelConfig(repoRoot) {
   const path9 = citadelConfigPath(repoRoot);
   if (!existsSync(path9)) {
     throw new ConfigError(
-      "No citadel.yaml found at the repository root. Run `npx maester init` to create one.",
+      "No citadel.yaml found at the repository root. Run `npx baller-maester init` to create one.",
       { filePath: path9 }
     );
   }
@@ -1275,7 +1275,7 @@ var CITADEL_HEADER = `# citadel.yaml
 # per-source \`destination\` always wins over the configured base.
 #
 # Run \`maester sync\` (or \`npm run maester:sync\`) to refresh every source in
-# one pass. Generated by \`npx maester init\` and safe to commit. Secret
+# one pass. Generated by \`npx baller-maester init\` and safe to commit. Secret
 # values are never stored here \u2014 only the names of environment variables
 # that hold them.
 
@@ -1286,7 +1286,7 @@ var MAESTER_HEADER = `# maester.yaml
 # that pulls from it. It is a manifest only \u2014 the documents themselves live
 # wherever the \`path\` fields point, and \`maester\` does not modify them.
 #
-# Generated by \`npx maester publish\` and safe to commit.
+# Generated by \`npx baller-maester publish\` and safe to commit.
 
 `;
 async function writeCitadelConfig(repoRoot, config) {
@@ -1443,7 +1443,7 @@ var citadel_awareness_default = '## Citadel awareness\n\nThis repository is a **
 var connector_policy_default = "## Connector tools (traveling maesters)\n\nThis citadel may expose one or more **traveling maesters** as MCP tools whose\nnames begin with the connector slug (e.g. `team_gl__list_issues`).\n\n- Their output is **live, point-in-time data** from an external service. Cite\n  specific identifiers (issue iids, ticket numbers) when surfacing it, do not\n  treat it as a stable corpus, and flag the **freshness verdict** in your\n  answer when it is not `up-to-date`.\n- The tools' arguments and return shapes are described in MCP `tools/list`;\n  do not assume undocumented fields.\n- Connector tool results are JSON envelopes carrying a `dataSchema` version\n  alongside the payload \u2014 if your reading of the data depends on a specific\n  shape, branch on `dataSchema`.\n";
 
 // src/core/skill/templates/content/freshness-awareness.md
-var freshness_awareness_default = '## Freshness awareness\n\nCitadel content can drift out of date when remote sources advance after the\nlast sync. The Grand Maester is **auto-sync directed**: when the citadel is\nbehind, refresh it before reading rather than relying on stale content.\n\n**Auto-sync policy**\n\nWhen you discover that the citadel is behind \u2014 either from the Claude Code\npre-read hook\'s `additionalContext` message, or from a manual run of\n`npx maester status` \u2014 follow these steps without prompting the user:\n\n1. Run `npx maester sync` to refresh every configured source.\n   - Exits 0 on success.\n   - Exits non-zero if any source failed (missing auth env var, ref typo,\n     network error). Report the failure to the user and proceed cautiously.\n2. **Invalidate the pre-read hook\'s debounce cache** so the next read\n   observes fresh state instead of the stale verdict captured before the\n   sync:\n   ```\n   rm -f .maester/.skill-cache.json\n   ```\n3. Proceed with the original read of the citadel file.\n\nYou do not need to ask the user before syncing. `maester sync` is read-only\nagainst the remote sources it pulls from; it only materializes content the\n`citadel.yaml` already declared. The same sync the user would run manually.\n\n**Don\'t loop on failures.** If `maester sync` fails (or the hook reports a\n`failed` verdict from `maester status`), do **not** retry sync repeatedly.\nSurface the failure to the user, proceed with the read, and flag that cited\ncontent may be stale.\n\n**Avoid redundant syncs within a session.** Once you have synced and\ninvalidated the cache, ignore any further "citadel is behind" messages that\narrive before you have done another citadel read \u2014 they are cached signals\ncaptured before your sync completed.\n\n**Manual status check**\n\n```\nnpx maester status\n```\n\nExit codes:\n\n- **`0`** \u2014 every source is up to date.\n- **`1`** \u2014 at least one source is behind (remote advanced, manifest\n  changed, or never-synced). Run the auto-sync policy above.\n- **`2`** \u2014 the status check itself failed. Surface to the user; proceed\n  with a caveat that staleness cannot be verified.\n\nFor machine-readable output, pass `--json` and parse the NDJSON stream on\nstdout. The final line contains `{ "type": "summary", "upToDate": N,\n"behind": N, "failed": N }`.\n\n**On Claude Code specifically**, a `PreToolUse` hook installed by\n`maester skill install` runs the status check automatically before any\n`Read`, `Glob`, or `Grep` targeting a path under `{{baseDir}}/`. The\nhook debounces (default 300s, override with `MAESTER_SKILL_STATUS_TTL`) so\nthe check does not run more than once per session for routine reads.\n';
+var freshness_awareness_default = '## Freshness awareness\n\nCitadel content can drift out of date when remote sources advance after the\nlast sync. The Grand Maester is **auto-sync directed**: when the citadel is\nbehind, refresh it before reading rather than relying on stale content.\n\n**Auto-sync policy**\n\nWhen you discover that the citadel is behind \u2014 either from the Claude Code\npre-read hook\'s `additionalContext` message, or from a manual run of\n`npx baller-maester status` \u2014 follow these steps without prompting the user:\n\n1. Run `npx baller-maester sync` to refresh every configured source.\n   - Exits 0 on success.\n   - Exits non-zero if any source failed (missing auth env var, ref typo,\n     network error). Report the failure to the user and proceed cautiously.\n2. **Invalidate the pre-read hook\'s debounce cache** so the next read\n   observes fresh state instead of the stale verdict captured before the\n   sync:\n   ```\n   rm -f .maester/.skill-cache.json\n   ```\n3. Proceed with the original read of the citadel file.\n\nYou do not need to ask the user before syncing. `maester sync` is read-only\nagainst the remote sources it pulls from; it only materializes content the\n`citadel.yaml` already declared. The same sync the user would run manually.\n\n**Don\'t loop on failures.** If `maester sync` fails (or the hook reports a\n`failed` verdict from `maester status`), do **not** retry sync repeatedly.\nSurface the failure to the user, proceed with the read, and flag that cited\ncontent may be stale.\n\n**Avoid redundant syncs within a session.** Once you have synced and\ninvalidated the cache, ignore any further "citadel is behind" messages that\narrive before you have done another citadel read \u2014 they are cached signals\ncaptured before your sync completed.\n\n**Manual status check**\n\n```\nnpx baller-maester status\n```\n\nExit codes:\n\n- **`0`** \u2014 every source is up to date.\n- **`1`** \u2014 at least one source is behind (remote advanced, manifest\n  changed, or never-synced). Run the auto-sync policy above.\n- **`2`** \u2014 the status check itself failed. Surface to the user; proceed\n  with a caveat that staleness cannot be verified.\n\nFor machine-readable output, pass `--json` and parse the NDJSON stream on\nstdout. The final line contains `{ "type": "summary", "upToDate": N,\n"behind": N, "failed": N }`.\n\n**On Claude Code specifically**, a `PreToolUse` hook installed by\n`maester skill install` runs the status check automatically before any\n`Read`, `Glob`, or `Grep` targeting a path under `{{baseDir}}/`. The\nhook debounces (default 300s, override with `MAESTER_SKILL_STATUS_TTL`) so\nthe check does not run more than once per session for routine reads.\n';
 
 // src/core/skill/templates/content/state-awareness.md
 var state_awareness_default = '## State awareness (canon vs draft)\n\nEvery citadel file may declare a publication state of `canon` (authoritative)\nor `draft` (work-in-progress). The state lives **inline** in the file using\nthe format\'s native convention:\n\n- **Markdown / MDX (`.md`, `.mdx`)** \u2014 `state` field inside YAML frontmatter\n  at the top of the file:\n  ```\n  ---\n  state: canon\n  ---\n  ```\n- **HTML (`.html`, `.htm`)** \u2014 first-line HTML comment:\n  `<!-- state: canon -->`\n- **YAML / JSON (`.yaml`, `.yml`, `.json`)** \u2014 a top-level `state` key.\n- **Plain text (`.txt`)** \u2014 `state: canon` as the very first line.\n\nFiles without inline state default to `draft`.\n\n**Policy when answering from the citadel:**\n\n1. **Prefer `canon` files** as the authoritative source of truth. When a\n   `canon` file answers the question, cite it and stop there.\n2. **`draft` files are informational only.** Cite them when no `canon`\n   alternative exists, but mark the citation explicitly: "(draft \u2014 work in\n   progress)" alongside the file path so the user knows the source is not yet\n   stable.\n3. **Never mix the two without labeling.** If you draw from both canon and\n   draft files in one answer, separate the two and tell the user which fact\n   came from which kind of source.\n';
@@ -1483,7 +1483,7 @@ function buildClaudeMaesterBlock(version) {
       PreToolUse: [
         {
           matcher: "Read|Glob|Grep",
-          hooks: [{ type: "command", command: "npx maester skill runtime preread" }]
+          hooks: [{ type: "command", command: "npx -y baller-maester skill runtime preread" }]
         }
       ]
     }
@@ -1729,7 +1729,7 @@ function decideAction2(existing, previousVersion, newVersion, newContent) {
 }
 
 // src/core/skill/templates/content/connector-policy-fallback.md
-var connector_policy_fallback_default = "## Connector tools (traveling maesters)\n\nThis citadel may expose one or more **traveling maesters** as connectors. Your\nagent platform does not speak MCP, so connector operations are reached via the\nfallback CLI:\n\n```\nnpx maester connector list\nnpx maester connector exec <connector-name> <operation> [--key value]...\n```\n\n- `connector list` prints the configured connectors and the operations they\n  expose.\n- `connector exec` invokes an operation and writes a JSON envelope to stdout.\n  Exit code `0` is success, `1` is a connector-level failure (auth, remote\n  error, invalid args), `2` is an invocation-level error (no such connector,\n  no citadel.yaml).\n\nTreat the data the same way as MCP tool output: live, point-in-time, cite\nspecific identifiers, flag freshness when it isn't `up-to-date`, and don't\nassume undocumented fields.\n";
+var connector_policy_fallback_default = "## Connector tools (traveling maesters)\n\nThis citadel may expose one or more **traveling maesters** as connectors. Your\nagent platform does not speak MCP, so connector operations are reached via the\nfallback CLI:\n\n```\nnpx baller-maester connector list\nnpx baller-maester connector exec <connector-name> <operation> [--key value]...\n```\n\n- `connector list` prints the configured connectors and the operations they\n  expose.\n- `connector exec` invokes an operation and writes a JSON envelope to stdout.\n  Exit code `0` is success, `1` is a connector-level failure (auth, remote\n  error, invalid args), `2` is an invocation-level error (no such connector,\n  no citadel.yaml).\n\nTreat the data the same way as MCP tool output: live, point-in-time, cite\nspecific identifiers, flag freshness when it isn't `up-to-date`, and don't\nassume undocumented fields.\n";
 
 // src/core/skill/templates/shells/agents-md.ts
 var PREAMBLE = `# AGENTS.md
@@ -2518,7 +2518,7 @@ function validateTag(value) {
 
 // package.json
 var package_default = {
-  version: "0.4.0"};
+  version: "0.4.1"};
 var PACKAGE_VERSION = package_default.version;
 
 // src/core/skill/version.ts
@@ -2755,7 +2755,7 @@ async function runInit(ctx) {
       ctx.prompts.log.info(`Remember to set these env vars before syncing: ${summary}`);
     }
     await maybeInstallSkill(ctx, baseDir ?? DEFAULT_BASE_DIR);
-    ctx.prompts.outro("Next: run `npx maester sync` to fetch your sources.");
+    ctx.prompts.outro("Next: run `npx baller-maester sync` to fetch your sources.");
     return 0;
   } catch (err) {
     if (err instanceof PromptCancelledError) {
@@ -3946,7 +3946,7 @@ function summarize(result) {
   return parts.join(", ");
 }
 function buildHookResponse(verdict) {
-  const detail = verdict.verdict === "failed" ? `Citadel status check failed: ${verdict.summary}. Proceed with the read and flag that cited content may be stale; do not retry sync in a loop.` : `Citadel is behind (${verdict.summary}). Auto-sync policy: run \`npx maester sync\`, then \`rm -f .maester/.skill-cache.json\` to invalidate this hook's cache, then proceed with the read. Do not prompt the user \u2014 sync is read-only against the configured remotes.`;
+  const detail = verdict.verdict === "failed" ? `Citadel status check failed: ${verdict.summary}. Proceed with the read and flag that cited content may be stale; do not retry sync in a loop.` : `Citadel is behind (${verdict.summary}). Auto-sync policy: run \`npx baller-maester sync\`, then \`rm -f .maester/.skill-cache.json\` to invalidate this hook's cache, then proceed with the read. Do not prompt the user \u2014 sync is read-only against the configured remotes.`;
   const response = {
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
@@ -5098,7 +5098,7 @@ function maybeRenderHelpVersionBanner(argv) {
   const wantsVersion = tail.includes("--version") || tail.includes("-V");
   if (!wantsHelp && !wantsVersion) return;
   const theming = createTheming();
-  const subtitle = wantsVersion ? "v0.4.0 \xB7 living specs" : "living specs \xB7 v0.4.0";
+  const subtitle = wantsVersion ? "v0.4.1 \xB7 living specs" : "living specs \xB7 v0.4.1";
   const banner = bannerForContext(theming, readColumns(), subtitle);
   if (banner.length > 0) {
     process.stdout.write(`${banner}
@@ -5116,7 +5116,7 @@ function toExitCode(value) {
 }
 function buildProgram() {
   const program = new Command();
-  program.name("maester").description("Aggregate documentation from many sources into one citadel.").version("0.4.0", "-V, --version", "Print the maester version.").option("--verbose", "Show verbose output").option("--quiet", "Suppress all output except errors").option("--json", "Emit machine-readable JSON output (one object per line)").option("--color", "Force colored output (overrides auto-detection)").option("--no-color", "Disable colored output (overrides auto-detection)").option("--theme <theme>", "Theme override: 'dark' or 'light'").option("--no-welcome", "Suppress the first-run welcome banner").enablePositionalOptions(false).allowExcessArguments(false);
+  program.name("maester").description("Aggregate documentation from many sources into one citadel.").version("0.4.1", "-V, --version", "Print the maester version.").option("--verbose", "Show verbose output").option("--quiet", "Suppress all output except errors").option("--json", "Emit machine-readable JSON output (one object per line)").option("--color", "Force colored output (overrides auto-detection)").option("--no-color", "Disable colored output (overrides auto-detection)").option("--theme <theme>", "Theme override: 'dark' or 'light'").option("--no-welcome", "Suppress the first-run welcome banner").enablePositionalOptions(false).allowExcessArguments(false);
   registerConnector(program, () => buildContext(extractFlags(program.opts())));
   registerInit(program, () => buildContext(extractFlags(program.opts())));
   registerMcp(program, () => buildContext(extractFlags(program.opts())));
@@ -5154,7 +5154,7 @@ async function runNoArgs(ctx) {
   const roles = detectRoles(ctx.repoRoot.path);
   const showWelcome = !roles.hasCitadel && !roles.hasMaester && !ctx.flags.noWelcome;
   if (showWelcome) {
-    const banner = bannerForContext(ctx.theming, readColumns(), "living specs \xB7 v0.4.0");
+    const banner = bannerForContext(ctx.theming, readColumns(), "living specs \xB7 v0.4.1");
     if (banner.length > 0) {
       process.stdout.write(`${banner}