boxbox-plugin 0.0.0-stage → 0.2.7

package/payload/codex/install.mjs

@@ -0,0 +1,150 @@
+import      { spawnSync                                                        } from "node:child_process"        ;
+import      { createHash                                                       } from "node:crypto"               ;
+import      { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"                   ;
+import      { join, resolve                                                    } from "node:path"                 ;
+import      { fileURLToPath                                                    } from "node:url"                  ;
+import      {
+              configureSkill                                                 ,
+              engineCommand                                                  ,
+              findCommand                                                    ,
+              hookCommands                                                   ,
+              pathLaunchers                                                  ,
+              supportedNode                                                  ,
+                                                                               } from "./platform.mjs"            ;
+
+import      { installationState                                                } from "./install-state.mjs"       ;
+import      { claudeRegistration                                               } from "./claude-registration.mjs" ;
+import      { codexRegistration                                                } from "./codex-registration.mjs"  ;
+
+const root       = fileURLToPath(new URL("./", import.meta.url))                    ;
+const windows    = process.platform === "win32"                                     ;
+const engineOnly = process.argv.length === 3 && process.argv[2] === "--engine-only" ;
+
+function fail(message) {
+	console.error(`[BoxBox] ${message}`);
+	process.exit(1);
+}
+
+function run(executable, args, options = {}) {
+	const child = spawnSync(executable, args, { stdio: "inherit", ...options });
+	if (child.error) fail(`Cannot run ${executable}: ${child.error.message}`);
+	if (child.signal) fail(`${executable} terminated by ${child.signal}`);
+	if (child.status !== 0) {
+		const details = String(child.stderr || child.stdout || "").trim();
+		console.error(`[BoxBox] ${executable} ${args.join(" ")} failed${details ? `:\n${details}` : "."}`);
+		process.exit(child.status ?? 1);
+	}
+	return child;
+}
+
+function command(name) {
+	const resolved = findCommand(name);
+	if (resolved) return resolved;
+	fail(`${name} was not found on PATH. Install ${name === "npm" ? "Node.js with npm" : "the selected host CLI with plugin support"}, open a new terminal, then rerun the BoxBox installer.${windows ? " Use the standard npm installation or a native host .exe." : ""}`);
+}
+
+function invoke(tool, args, options) {
+	return run(tool.executable, [...tool.args, ...args], options);
+}
+
+function bundledEngine(tarball, metadata) {
+	if (typeof metadata.engineSha256 !== "string" || !/^[0-9a-f]{64}$/u.test(metadata.engineSha256)) fail("Bundled engine integrity metadata is missing or invalid. Reinstall this BoxBox installer package, then rerun it.");
+	if (!existsSync(tarball)) fail(`Bundled engine is missing: ${tarball}. Reinstall this BoxBox installer package, then rerun it.`);
+	const actual = createHash("sha256").update(readFileSync(tarball)).digest("hex");
+	if (actual !== metadata.engineSha256) fail("Bundled engine integrity check failed. The bundled engine bytes do not belong to this installer. Reinstall this BoxBox installer package, then rerun it.");
+	return tarball;
+}
+
+if (process.argv.length > 2 && !engineOnly) fail("Usage: node install.mjs [--engine-only]");
+if (!supportedNode(process.versions.node)) fail(`Node.js >=22.22.3 is required; found ${process.versions.node}. Install a supported Node.js release and rerun the BoxBox installer.`);
+
+const metadata = JSON.parse(readFileSync(join(root, "bundle.json"), "utf8"));
+if (!["codex", "claude"].includes(metadata.host)) fail("The installed payload has an invalid host. Rerun the BoxBox installer.");
+const state = installationState(root, metadata);
+if (state.read()?.phase !== "prepared") fail("A fresh parent installation receipt is required. Rerun the BoxBox installer.");
+const tarball = bundledEngine(join(root, "packages", `${metadata.name}-${metadata.version}.tgz`), metadata) ;
+const npm     = command      ("npm"                                                                       ) ;
+const quiet   = { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }                                    ;
+invoke(npm, ["--version"], quiet);
+const host = engineOnly ? undefined : command(metadata.host);
+if (host) {
+	invoke(host, ["--version"], quiet);
+	invoke(host, ["plugin", metadata.host === "codex" ? "add" : "install", "--help"], quiet);
+}
+
+const claude = host && metadata.host === "claude" ? claudeRegistration(root, metadata, (args, options) => invoke(host, args, options)) : undefined;
+const codex = host && metadata.host === "codex" ? codexRegistration(root, metadata, (args, options = {}) => {
+	const child = spawnSync(host.executable, [...host.args, ...args], { stdio: "inherit", ...options });
+	if (child.error) throw child.error;
+	if (child.signal || child.status !== 0) {
+		const details = String(child.stderr || child.stdout || "").trim();
+		throw new Error(`Codex ${args.join(" ")} failed${details ? `: ${details}` : ""}`);
+	}
+	return child;
+}) : undefined;
+try {
+	claude?.preflight();
+	codex?.preflight();
+} catch (error) {
+	fail(error.message);
+}
+
+const runtimeDirectory = join(root, "runtime");
+mkdirSync(runtimeDirectory, { recursive: true });
+writeFileSync(join(runtimeDirectory, "package.json"), JSON.stringify({ private: true, type: "module", name: `boxbox-${metadata.host}-runtime` }, null, "\t") + "\n");
+invoke(npm, ["install", "--ignore-scripts", "--no-audit", "--no-fund", "--save-exact", tarball], { cwd: runtimeDirectory });
+
+const node = realpathSync(process.execPath                                              ) ;
+const cli  = resolve     (runtimeDirectory, "node_modules", metadata.name, "dist/cli.js") ;
+if (!existsSync(cli)) fail("The local engine did not install correctly. Keep the npm error output and rerun the BoxBox installer.");
+const version = run(node, [cli, "--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }).stdout.trim();
+if (version !== metadata.version) fail(`Installed engine version mismatch: ${version}`);
+
+const plugin        = join(root, "plugin")                                                                                                                          ;
+const launcher      = join(plugin, "scripts/boxbox.mjs")                                                                                                            ;
+const configuration = join(plugin, "runtime.json")                                                                                                                  ;
+const previous      = existsSync(configuration) ? JSON.parse(readFileSync(configuration, "utf8")) : {}                                                              ;
+const skillCommand  = engineCommand(node, launcher, windows, metadata.host)                                                                                         ;
+const documents     = [join(plugin, "skills", metadata.name, "SKILL.md"), ...(metadata.host === "claude" ? [join(plugin, "agents/readability-inspector.md")] : [])] ;
+for (const path of documents) {
+	try {
+		writeFileSync(path, configureSkill(readFileSync(path, "utf8"), skillCommand, previous.skillCommand, windows));
+	} catch (error) {
+		fail(error.message);
+	}
+}
+writeFileSync(configuration, JSON.stringify({ node, cli, skillCommand }, null, "\t") + "\n");
+mkdirSync(join(plugin, "bin"), { recursive: true });
+for (const [path, text] of Object.entries(pathLaunchers(node, launcher))) writeFileSync(join(plugin, path), text, { mode: 0o755 });
+
+const hooksPath = join      (plugin, "hooks/hooks.json"     ) ;
+const hooks     = JSON.parse(readFileSync(hooksPath, "utf8")) ;
+for (const [event, mode] of [["SessionStart", "session"], ["PostToolUse", "post"], ["Stop", "stop"]]) {
+	for (const group of hooks.hooks[event]) {
+		for (const hook of group.hooks) {
+			delete hook.commandWindows;
+			delete hook.args;
+			Object.assign(hook, hookCommands(node, mode, metadata.host));
+		}
+	}
+}
+writeFileSync(hooksPath, JSON.stringify(hooks, null, "\t") + "\n");
+
+if (host) {
+	state.advance("host-registration-started");
+	try {
+		if (codex) codex.transition();
+		else {
+			invoke(host, ["plugin", "marketplace", "add", root]);
+			claude?.marketplace();
+			invoke(host, ["plugin", "install", `${metadata.name}@${metadata.marketplace}`, "--scope", "user"]);
+		}
+	} catch (error) {
+		fail(error.message);
+	}
+}
+claude?.verify();
+state.advance("verified");
+console.log(engineOnly ? "BoxBox local engine is ready; host checks and registration were skipped." : `BoxBox is installed for ${metadata.host === "codex" ? "Codex" : "Claude Code"}. Restart that host and select the BoxBox skill. Review the current hooks manually before relying on them.`);
+console.log(`Permanent installation: ${root}`);
+console.log("Approved TypeScript call and value declarations and Python simple assignments can format without an external formatter. Run check and guide, then format --dry-run before an explicit format request; other patterns require approval.");

package/payload/codex/platform.mjs

@@ -0,0 +1,106 @@
+import      { spawnSync    } from "node:child_process" ;
+import      { existsSync   } from "node:fs"            ;
+import      { homedir      } from "node:os"            ;
+import      { posix, win32 } from "node:path"          ;
+
+export function supportedNode(version) {
+	const [major, minor, patch] = version.split(".").map(Number);
+	return major > 22 || (major === 22 && (minor > 22 || (minor === 22 && patch >= 3)));
+}
+
+export function installationRoot(version, host, { windows = process.platform === "win32", environment = process.env, home = homedir() } = {}) {
+	if (!["codex", "claude"].includes(host)) throw new Error("Expected codex or claude installation host.");
+	if (windows) {
+		if (!environment.LOCALAPPDATA || !win32.isAbsolute(environment.LOCALAPPDATA)) throw new Error("LOCALAPPDATA must point to an absolute user data directory on Windows.");
+		return win32.join(environment.LOCALAPPDATA, "BoxBox", host === "codex" ? "Codex" : "Claude", version);
+	}
+	const data = environment.XDG_DATA_HOME || posix.join(home, ".local/share");
+	if (!posix.isAbsolute(data)) throw new Error("XDG_DATA_HOME must be an absolute directory when set.");
+	return posix.join(data, "boxbox", host, version);
+}
+
+function identifiesCodex(executable, probe) {
+	try {
+		const result = probe(executable, ["--version"], {
+			encoding: "utf8", shell: false, windowsHide: true,
+			timeout: 3_000, maxBuffer: 4_096, killSignal: "SIGKILL", stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		return result.status === 0 && !result.error && !result.signal
+			&& /^codex-cli \d+\.\d+\.\d+(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/iu.test(String(result.stdout ?? "").trim());
+	} catch {
+		return false;
+	}
+}
+
+/** Resolve standard Windows npm shims without a shell, and skip unrelated native programs named codex.exe. */
+export function findCommand(name, { windows = process.platform === "win32", node = process.execPath, path = process.env.PATH || "", exists = existsSync, probe = spawnSync } = {}) {
+	const paths = windows ? win32 : posix;
+	const directories = [...path.split(windows ? ";" : ":").filter(Boolean), paths.dirname(node)];
+	for (const directory of directories) {
+		if (windows) {
+			if (name === "npm" || name === "codex") {
+				const script = paths.join(directory, name === "npm" ? "node_modules/npm/bin/npm-cli.js" : "node_modules/@openai/codex/bin/codex.js");
+				if (exists(script)) return { executable: node, args: [script] };
+			}
+			if (name === "claude") {
+				const packaged = paths.join(directory, "node_modules/@anthropic-ai/claude-code/bin/claude.exe");
+				if (exists(packaged)) return { executable: packaged, args: [] };
+			}
+			const native = paths.join(directory, `${name}.exe`);
+			if (name !== "npm" && exists(native) && (name !== "codex" || identifiesCodex(native, probe))) return { executable: native, args: [] };
+		} else {
+			const executable = paths.join(directory, name);
+			if (exists(executable)) return { executable, args: [] };
+		}
+	}
+	return undefined;
+}
+
+export function shellQuote(value) {
+	return "'" + value.replaceAll("'", "'\\''") + "'";
+}
+
+export function powershellQuote(value) {
+	return "'" + value.replaceAll(/['\u2018\u2019\u201A\u201B]/gu, quote => quote + quote) + "'";
+}
+
+export function engineCommand(node, launcher, windows, host = "codex") {
+	if (windows && host === "claude") {
+		const payload = Buffer.from(JSON.stringify([node, launcher]), "utf8").toString("base64");
+		return `node -e "const [n,l]=JSON.parse(Buffer.from('${payload}','base64').toString('utf8'));const r=require('node:child_process').spawnSync(n,[l,...process.argv.slice(1)],{stdio:'inherit'});if(r.error){console.error(r.error.message);process.exit(1)}process.exit(r.status??1)" --`;
+	}
+	return windows ? `& ${powershellQuote(node)} ${powershellQuote(launcher)}` : `${shellQuote(node)} ${shellQuote(launcher)}`;
+}
+
+/**
+ * `boxbox` and `update` on the host's PATH. Claude Code adds an enabled plugin's `bin/` folder to the PATH of its
+ * shell, so the user can type `! update boxbox` in the prompt. `update` answers only `update boxbox` and refuses any
+ * other target, so it never stands in for another tool's command. The sh forms serve Git Bash and POSIX shells; the
+ * .cmd forms serve cmd.exe and PowerShell on Windows.
+ */
+export function pathLaunchers(node, launcher) {
+	const posix   = path => path.replaceAll("\\", "/")                                                    ;
+	const refusal = "update: only \\`update boxbox\\` is provided here (BoxBox plugin)."                   ;
+	return {
+		"bin/boxbox"     : `#!/bin/sh\n# Generated by the BoxBox installer.\nexec ${shellQuote(posix(node))} ${shellQuote(posix(launcher))} "$@"\n`,
+		"bin/boxbox.cmd" : `@echo off\r\nrem Generated by the BoxBox installer.\r\n"${node}" "${launcher}" %*\r\n`,
+		"bin/update"     : `#!/bin/sh\n# Generated by the BoxBox installer.\nif [ "\${1:-}" != boxbox ]; then printf '%s\\n' "${refusal}" >&2; exit 2; fi\nshift\nexec ${shellQuote(posix(node))} ${shellQuote(posix(launcher))} update "$@"\n`,
+		"bin/update.cmd" : `@echo off\r\nrem Generated by the BoxBox installer.\r\nif /i not "%~1"=="boxbox" (echo update: only "update boxbox" is provided here ^(BoxBox plugin^). 1>&2 & exit /b 2)\r\nshift\r\n"${node}" "${launcher}" update %1 %2 %3 %4 %5 %6 %7 %8 %9\r\n`,
+	};
+}
+
+export function configureSkill(skill, command, previousCommand, windows) {
+	const marker = "@BOXBOX_ENGINE_COMMAND@";
+	const oldCommand = skill.includes(marker) ? marker : previousCommand;
+	if (!oldCommand || !skill.includes(oldCommand)) throw new Error("The installed skill command is missing. Rerun the BoxBox installer to repair the plugin.");
+	return skill.replaceAll(oldCommand, () => command).replaceAll(windows ? "```bash" : "```powershell", windows ? "```powershell" : "```bash");
+}
+
+export function hookCommands(node, mode, host = "codex") {
+	if (host === "claude") return { command: node, args: ["${CLAUDE_PLUGIN_ROOT}/scripts/boxbox.mjs", "hook", mode] };
+	return {
+		command: `${shellQuote(node)} "\${PLUGIN_ROOT}/scripts/boxbox.mjs" hook ${mode}`,
+		commandWindows: `& ${powershellQuote(node)} "$env:PLUGIN_ROOT/scripts/boxbox.mjs" hook ${mode}`,
+	};
+}

package/payload/codex/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+	"name": "boxbox",
+	"version": "0.2.7",
+	"description": "Guides writing and refactoring TypeScript and Python, with syntax and tabular checks for TypeScript, Python, JSON and YAML and human-approved whitespace alignment.",
+	"author": {
+		"name": "Woo-JongHo"
+	},
+	"keywords": [
+		"readability",
+		"typescript",
+		"python",
+		"code-style",
+		"align",
+		"json",
+		"yaml"
+	],
+	"skills": "./skills/",
+	"interface": {
+		"displayName": "BoxBox",
+		"shortDescription": "Write, refactor and align code for tabular readability",
+		"longDescription": "Guides agent-owned TypeScript and Python writing and refactoring; checks TypeScript, Python, JSON and YAML and aligns approved tables one file at a time. Unsupported structures remain unchanged. Structural changes require separate behavior verification.",
+		"developerName": "Woo-JongHo",
+		"category": "Coding",
+		"capabilities": [
+			"Read",
+			"Write"
+		]
+	}
+}

package/payload/codex/plugin/hooks/hooks.json

@@ -0,0 +1,42 @@
+{
+	"description": "boxbox: inspects TypeScript, Python, JSON, and YAML session changes after matched file-edit and shell tools. Hooks are read-only by default; explicit align mode may apply approved alignment after tools. Stop never writes. Receipts stay in host plugin data; mode and update-cache state use user configuration. SessionStart may check GitHub tags once per day; BOXBOX_UPDATE_CHECK=0 disables that probe.",
+	"hooks": {
+		"SessionStart": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/scripts/boxbox.mjs\" hook session",
+						"timeout": 120,
+						"commandWindows": "node \"$env:PLUGIN_ROOT/scripts/boxbox.mjs\" hook session"
+					}
+				]
+			}
+		],
+		"PostToolUse": [
+			{
+				"matcher": "^(Write|Edit|MultiEdit|apply_patch|Bash)$",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/scripts/boxbox.mjs\" hook post",
+						"timeout": 120,
+						"commandWindows": "node \"$env:PLUGIN_ROOT/scripts/boxbox.mjs\" hook post"
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/scripts/boxbox.mjs\" hook stop",
+						"timeout": 120,
+						"commandWindows": "node \"$env:PLUGIN_ROOT/scripts/boxbox.mjs\" hook stop"
+					}
+				]
+			}
+		]
+	}
+}

package/payload/codex/plugin/scripts/boxbox.mjs

@@ -0,0 +1,42 @@
+import      { spawnSync                } from "node:child_process" ;
+import      { existsSync, readFileSync, readSync } from "node:fs"            ;
+import      { isAbsolute, resolve      } from "node:path"          ;
+import      { fileURLToPath            } from "node:url"           ;
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const configuration = resolve(root, "runtime.json");
+
+try {
+	if (!existsSync(configuration)) throw new Error("Local runtime is missing. Rerun the BoxBox installer before using this plugin.");
+	const runtime = JSON.parse(readFileSync(configuration, "utf8"));
+	for (const key of ["node", "cli"]) {
+		if (typeof runtime[key] !== "string" || !isAbsolute(runtime[key]) || !existsSync(runtime[key])) throw new Error(`Local runtime ${key} is missing. Rerun the BoxBox installer to repair the local runtime.`);
+	}
+	const env = { ...process.env };
+	let input;
+	let data;
+	if (process.argv[2] === "hook") {
+		data = env.PLUGIN_DATA || env.CLAUDE_PLUGIN_DATA;
+		if (!data || !isAbsolute(data)) throw new Error("Hook requires an absolute PLUGIN_DATA or CLAUDE_PLUGIN_DATA directory from the host; no project files were written.");
+		env.CLAUDE_PLUGIN_DATA = data;
+		env.CLAUDE_PLUGIN_ROOT = env.PLUGIN_ROOT || env.CLAUDE_PLUGIN_ROOT || root;
+		const chunks = [];
+		const buffer = Buffer.alloc(65536);
+		let size = 0;
+		for (;;) {
+			const count = readSync(0, buffer, 0, buffer.length, null);
+			if (!count) break;
+			size += count;
+			if (size > 1024 * 1024) throw new Error("Hook input exceeds the 1 MiB limit.");
+			chunks.push(Buffer.from(buffer.subarray(0, count)));
+		}
+		input = Buffer.concat(chunks);
+	}
+	const child = spawnSync(runtime.node, [runtime.cli, ...process.argv.slice(2)], { stdio: input ? ["pipe", "inherit", "inherit"] : "inherit", input, env });
+	if (child.error) throw child.error;
+	if (child.signal) throw new Error(`Engine terminated by ${child.signal}`);
+	process.exitCode = child.status ?? 1;
+} catch (error) {
+	console.error(`[BoxBox] ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+}

package/payload/codex/plugin/skills/boxbox/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: boxbox
+description: Write or refactor TypeScript/Python, or align or check TypeScript, Python, JSON or YAML when the user requests BoxBox or spreadsheet-style readability, comparing same-role rows in minimum-width columns. Also handles on-demand BoxBox session usage reports.
+---
+
+# BoxBox Code Readability
+
+Let the reader follow execution top to bottom and compare same-role rows vertically. Rows share a comparison purpose;
+columns are corresponding syntax boundaries, and cells hold their content. A comma in a nested call is not the same
+axis as an outer argument separator. Use minimum-width columns without inventing work, wrappers or parameters to fill a grid.
+
+Run the configured local launcher from the target repository root.
+
+## Monitor request
+
+When the user supplies `-monitor` (for example `/boxbox -monitor`), run the bundled launcher from the target repository:
+
+```bash
+@BOXBOX_ENGINE_COMMAND@ monitor --project --host auto --json
+```
+
+Complete this branch by reporting the returned HTML path, headline usage/change numbers and explicit unavailable or
+estimated fields; keep the HTML body out of the conversation. The command always writes a self-contained host page
+under the host's plugin data, including with `--json`. It requires absolute `CLAUDE_PLUGIN_DATA` or `PLUGIN_DATA`; if absent or relative,
+relay the setup error and use the host launcher/environment rather than choosing an arbitrary directory. An optional
+`--html <absolute-path>` replaces the default destination and must stay inside that same data folder. Use the user's explicit `--session`, `--host` or
+`--no-paths` selection when supplied; `--session` replaces `--project`. Auto host selects Codex when a Codex
+thread/session environment is present, otherwise Claude; choose explicitly for standalone sessions.
+
+The report contains no transcript text, commands or source content, makes no model call and shows no dollar cost.
+Old baselines can lack footprints, invalid fingerprints remain unknown and Codex exact step attribution is unavailable.
+A monitor request is not an instruction to align or refactor source. Continue source work only when it is also requested.
+
+## Choose the workflow
+
+| Request | Workflow | Allowed change |
+|---|---|---|
+| Write new code using BoxBox readability | **Write** | The agent implements the requested behavior using applicable guidance. |
+| Restructure existing code for BoxBox readability | **Refactor** | The agent improves structure within the authorized scope while preserving required behavior. |
+| Align existing code without structural changes | **Align** | The engine changes approved horizontal whitespace only. |
+| Inspect or review readability | **Check** | Report original-source syntax and readability without changing source. |
+
+Write and Refactor are agent workflows, not CLI generation commands. Follow an explicit mode choice. For an ambiguous
+"fix" request, check first and clarify when the choice between structural changes and alignment affects the result.
+Preview is an execution option for every workflow: present a proposed diff without modifying the target file.
+Author one file at a time within the user's authorized scope; continue across authorized files without requiring fresh feedback for each file.
+For engine Check or Format, use repeated `--file` or `--directory` for an authorized multi-file selection; Align and Guide remain single-file commands.
+
+## Running the engine
+
+Every check and fix goes through this plugin's permanent local Node launcher, already configured by the installer. Run the commands below from the root of the target repository. No BOXBOX_CLI setup is needed. Never fetch a separate registry package for the engine. On Windows, run these commands through PowerShell.
+
+```bash
+@BOXBOX_ENGINE_COMMAND@ doctor                      # runtime, parser, config and approval data status
+@BOXBOX_ENGINE_COMMAND@ check --source --file <file> --json  # source syntax/readability; no formatter or working copy
+@BOXBOX_ENGINE_COMMAND@ guide  --file <file> --json  # approved rules and examples that apply to this file
+@BOXBOX_ENGINE_COMMAND@ guide  --file <file> --authoring --json
+@BOXBOX_ENGINE_COMMAND@ align  --file <file> --dry-run --json
+@BOXBOX_ENGINE_COMMAND@ align  --file <file> --json
+@BOXBOX_ENGINE_COMMAND@ format --file <file> --dry-run --json
+@BOXBOX_ENGINE_COMMAND@ format --file <file> --json
+```
+
+- Use `check --source` for readability preflight, selected Check workflows and checks after Write/Refactor/Align. It
+  reads source syntax, detected groups and approval facts without a formatter, formatting working copy or write attempt.
+  For an authorized formatter/editor/CI canonical check, use `check` without `--source`; the default still verifies the
+  configured formatter-then-BoxBox output and requires working-copy write permission.
+- If `doctor`, `align` or `format` reports a formatter warning, relay it to the user with its conditions intact: a warning saying a formatter "may be in use" does not establish that it runs.
+- The public commands support TypeScript, Python, strict JSON and YAML 1.2. Check and Format accept repeated `--file`
+  or bounded recursive `--directory`; each batch format is atomic per file and reports earlier writes if another file
+  fails. Align and Guide accept one file. Python inspection and formatting require a runnable `python3`.
+- Structured Check accepts `.json`, `.yaml` and `.yml`. It considers only runs of at least three adjacent,
+  same-level, single-line scalar mapping entries for alignment. YAML multiline values, block scalars, anchors,
+  aliases, tags, complex keys, flow collections, sequences, directives and document markers are unsupported.
+  Report those rows and keep their bytes unchanged.
+- Engine support is separate from write authorization. The recommended preset contains five approved
+  TypeScript/Python conventions. JSON/YAML Align must refuse until a complete applicable approval proof exists.
+- `guide --authoring` reads approved guidance for the target language and scope, including a new or empty file.
+  Its examples guide composition; they do not prove that a proposed file is approved or safe to write.
+- `align` runs without an external formatter and changes horizontal layout only. It preserves non-whitespace tokens,
+  comments, identifiers and order, leading indentation, physical lines and structural AST. If the engine needs wrapping,
+  operator movement or another structural change, report the refusal; stay within the selected mode.
+- A newly detected shape or axis set has its own approval identity and suppresses an overlapping legacy group. Existing
+  approvals do not expand to it. A public whole-file write is denied when any candidate `PASS`/`FIXABLE` group lacks
+  approval, including an unchanged group. Per-group selective writes remain deferred.
+- `format` retains the formatter pipeline for explicit requests to use it. If a formatter is configured for the language, it runs first.
+  Canonical Check and `format --dry-run` also execute a configured formatter twice on working copies; inspect its command
+  and arguments in the effective config before running them. Use existing authorization; ask only when executing that
+  command is outside the authorized work. Canonical Check preserves the target and reports `canonical` verification separately
+  from the original source results; exit 0/1 compares final canonical bytes with the source, while an error/refusal exits 2.
+  Human approval proof, re-parsing, preservation and a two-run fixed point must pass; report any refusal reason to the user.
+- Do not look for or run other alignment scripts or bypass options.
+
+## Write and Refactor
+
+1. Run `guide --authoring --json` for the intended file before composing a change. For TypeScript it also returns
+   `columnSets` (every registered kind with its ordered columns; `approved` marks kinds an approved rule covers; `{i}`
+   is a per-position column) and `axisNotes` (what each column means). Python returns source-free representative variants
+   with exact legacy approval axes; `semanticKind`/`sourceContext` are descriptive labels, not new approval identities.
+   Use the returned sets as the vocabulary for naming cells instead of reading the whole readability contract; open the contract sections cited below only for a judgment the
+   vocabulary cannot settle. They are vocabulary, not approval. For an existing file, also run
+   `check --source --json` and read its definitions, callers and relevant tests before changing its structure.
+2. Design the rows before writing. For every group of three or more same-role values you are about to write, name the
+   column set they share and compose each value as one row of it, instead of writing a convenient shape and aligning
+   afterwards: readers with one argument shape, one field per row, `.map` rows over comparable lists, a branch chosen
+   in one row. Follow [grid-first authoring](references/readability-contract.md#grid-first-authoring), including its
+   limits: no padding wrappers, keep other roles outside the table, preserve behavior, and measure hot paths.
+   Then build a boundary inventory for the requested rows: name each cell, its syntax boundary and its comparison region.
+   For a member call, inspect `receiver | final . | method | ( | arguments | )`; for a guard, inspect `condition | return | value`.
+   Match roles and nesting depth before matching punctuation. Function signatures, bodies and call sites have separate
+   regions. Per-field JSDoc alone does not change the role of ordinary data properties: same-role fields
+   share one name/colon/type table. The bounded `documented-data-members` kind handles required properties in data-only
+   interfaces; documented Port methods and optional capabilities retain their separate boundaries. Read the rule's
+   actual scope and a counterexample before applying an exception. For member calls, early returns or nested type members, read
+   [column-sharing regions](references/readability-contract.md#column-sharing-regions) before choosing widths or moving rows.
+3. Author the requested implementation or structural improvement. Preserve execution order, public contracts and meaningful
+   differences. An overlong exception is a reason to inspect responsibility and data flow, not permission to add abstractions
+   just to shorten a column. Structural guidance is advisory; report unsupported patterns instead of inventing approval data.
+   An explicit user request for a local layout change can guide this authoring pass; it does not create reusable preset
+   approval or bypass the deterministic Align procedure.
+   When authoring or normalizing internal imports, follow the target project's import conventions and package
+   boundaries; retain relative imports where its current contract requires them. Otherwise use its configured alias
+   (such as `@/`) where equivalent resolution is verified. Read its effective compiler configuration, including inherited mappings, and
+   runtime/build/test resolvers first. An alias is project-relative, not a machine-absolute path. Preserve external
+   package and `node:` specifiers, module evaluation order and unresolved dynamic paths. Path changes belong to
+   Write/Refactor, not Align. Report unsupported alias resolution; change resolver configuration only within the
+   authorized scope. Verify type checking and affected build, runtime or isolated installation paths before claiming
+   migration complete.
+4. For preview, show the proposed diff and distinguish checks run on a proposal from checks run on the target. For an
+   authorized application, inspect the diff, run relevant syntax/type and behavior checks, and assess performance-sensitive
+   changes with appropriate evidence. Alignment cannot prove behavioral equivalence or performance.
+5. Where approved and requested, use Align below for final whitespace. Then run the final `check --source --json`, passing each
+   boundary you named in step 2 as `--expect-axis <axis>` (repeatable). The engine returns `axisExpectation`: `covered`
+   (axis, group count, start lines), `missing` (no group carries it) and `unknown` (not an axis name; fix the spelling).
+   It never changes the exit status and shows only that a group carries the axis, not that its columns are right.
+   Account for every `missing` axis, including unsupported or single-row boundaries. Inspect their actual columns and
+   record manual verification or an unresolved coverage gap. Completion requires
+   each requested boundary to be verified or explicitly reported unresolved, alongside remaining findings and checks not run.
+   When the user or project instructions require issue-history records, use that schema within the authorized scope to
+   retain the reproduction, cause, decision and verification evidence, including failed attempts and unresolved work.
+
+## Check and Align
+
+When using the read-only `readability-inspector`, give it one target file and a report path owned by the calling agent
+or controller. Capture its full report from the host result channel and save it at that path using the caller's existing
+authorized permissions. Keep the inspector read-only. Return only a 3–5 line verdict and the saved path in the main
+conversation.
+
+1. Run `check --source --json`. Read `syntax.status` (`valid`, `invalid` or parser `error`), `formatReadiness` (approval
+   eligibility; write verification is still `not-run`), `unsupported`, `groups` and their `PASS`, `FIXABLE`,
+   `REFUSE` states. This source-only report does not verify a formatter canonical result or authorize a write. A refused
+   group stays unchanged by alignment.
+2. Read `guide --json` for applicable approved rules. With no approved rule, report the candidate and missing evidence;
+   do not align it by hand, auto-approve it or use a raw writer.
+3. For Check, report findings. For Align preview, run `align --dry-run --json`. For authorized application, inspect the
+   dry-run result and then run `align --json`; report refusal reasons without falling back to `format` or Refactor.
+4. After application, rerun `check --source --json`, reconcile user-requested boundaries with the final returned axes, and report
+   missing coverage alongside the remaining `misaligned` count. Zero detected groups
+   or zero misalignment does not prove that unsupported code follows the requested style. Report only validations actually run.
+
+## Rule documents
+
+Read the documents in this folder when a judgment is needed.
+
+- `references/charter.md` — principles and safety invariants
+- `references/grammar.md` — grammar units, patterns, roles, paragraphs (split with a blank line when the property differs)
+- `references/readability-contract.md` — confirmed rules, grid-first authoring, discarded rules, column-check order
+- `references/typescript-grid-template.md` — per-role TypeScript table templates
+
+## Authoring hooks
+
+The plugin defaults to `check` mode: inspect session changes and report without writing source. `refactor` mode also
+keeps hooks read-only; the agent owns structural edits. `off` skips hook inspection. Only the user's explicit
+`boxbox mode align` choice enables PostToolUse alignment, through the approved horizontal-whitespace pipeline and
+after-write recheck. A refusal leaves that file unchanged. Stop always inspects without writing and can request at
+most one continuation. Project mode overrides the global default; a valid `BOXBOX_MODE` overrides both for the process.
+Do not select `align` mode merely because a user requested a Check or Refactor workflow.
+
+The npm-installed launcher requires the host's plugin data folder and writes versioned receipts there. Direct CLI
+hooks installed with `hooks install` can fall back to `.boxbox/hooks` when the host provides no data folder. Receipts
+record observed mode, coverage and successful alignment; they never approve rules. A failing PostToolUse report names
+up to three affected files and suppresses duplicate matched-tool feedback until the observed source snapshot changes;
+Stop still performs its read-only completion check. Automatic hooks cover session changes; editor/pre-commit/CI
+canonical checks use the default variant in Running the engine.
+
+An update notice is informational. For a user-requested public update, relay `npx boxbox-plugin`; use
+`boxbox update --source <checkout>` only as an explicit development override. Its installed-version check must succeed
+for the selected host, and the host must restart. An optional `statusline` is one row, separate from monitoring.

package/payload/codex/plugin/skills/boxbox/references/charter.md

@@ -0,0 +1,72 @@
+# BoxBox Charter
+
+Status: confirmed (M1.8 S1) · Date: 2026-09-30
+
+This document is **layer 0** of the five normative layers. Grammar (layer 1), surface forms (layer 2), conventions (layer 3) and the example book (layer 4) all sit below it, and when they conflict with this document, this document wins. Only maintainers may change it.
+
+## Core (generating source)
+
+The three lines below are copied verbatim to the top of `SKILL.md` and into the marked section of a user repository's `AGENTS.md`. When the wording changes, the copies must change with it (pinned by a test in M1.8 S7).
+
+<!-- boxbox:core:begin -->
+1. Write same-role code in the same pattern. Code is language.
+2. Simplify first, align second. Never cover a reducible difference with whitespace.
+3. Fix automatically only whitespace, and only when certain. Suggest everything else.
+<!-- boxbox:core:end -->
+
+## 1. Principle — readability
+
+Let the reader follow the flow from top to bottom and compare same-role code vertically. Every rule in this product exists for this one sentence.
+
+## 2. Values — code is language
+
+- Code is made of **words** (names), **sentences** (one line's declaration, call or condition), **paragraphs** (groups of sentences with one purpose) and **texts** (files).
+- Write same-role sentences in **the same pattern**. Uniformity does not mean fitting every line to the longest one; it means giving the same role **the same minimal composition**.
+- Symbols such as `=`, `:`, `from` and `(` are **particles** that mark roles inside a sentence. Alignment lines up the particles of the same pattern vertically so the reader can scan roles column by column.
+- The same grammar serves both **guiding what gets written** (GUIDE) and **checking it** (REVIEW). The two must never look at different standards.
+- We also know the limits of this metaphor. Understanding code relies mainly on reasoning, not on language ability. So patterns are defined by **role**, not by English word order, and the goal is to reduce the reader's reasoning load.
+
+## 3. Identity — a deterministic program
+
+- boxbox is a **deterministic program**, and the agent plugin is a channel that calls it. Rules are set by the program and by human approval, not by an agent's judgment.
+- So it has what a program needs: a version, a config schema, exit codes, and a CLI that runs without an agent (CI, hooks, editors).
+- Users can change **conventions** (layer 3) and **examples** (layer 4) to their taste. **Invariants** (section 5) can be changed by no one. Users write only one file themselves, the config; everything else is written by tools and approved by people.
+
+## 4. Order — simplify first, align second, verify always
+
+*Simplify first. Align second. Verify always. — Follow the structure. Don't force it.*
+
+- Alignment is not the goal. A structure lengthened by an exceptional element is first removed, wrapped inward or normalized.
+- Only real, irreducible information is accepted as cell data and aligned at minimum width.
+- Covering a reducible difference with whitespace alignment, or letting whitespace pull semantic units apart, is a failure.
+
+## 5. Invariants — unchangeable and not configurable
+
+An attempt to turn off any item in this list through configuration is not silently ignored; it is a schema error. An item with an empty "enforced at" exists only as a documented promise, and moving it into code is roadmap work.
+
+| # | Invariant | Enforced at |
+|---|---|---|
+| 1 | **Only whitespace changes.** Automatic fixes touch only spaces, tabs and line breaks. Non-whitespace tokens, strings and comments must be byte-identical | `common/09_preservation.ts`, `typescript/16_token-preservation.ts`, `test/mutation.test.ts` |
+| 2 | **Output is re-parsed.** A fix is written only when the language's official parser rereads it with the same diagnostics | `common/08_parse-check.ts`, `typescript/07_align-tables.ts` |
+| 3 | **When uncertain, do not touch.** `REFUSE` when it cannot be split losslessly, `UNCERTAIN` when classification is ambiguous. A missed fix is better than a wrong fix | `REFUSE`: across the engine · `UNCERTAIN`: not implemented |
+| 4 | **Automatic fixes only for 3+ rows.** Two-row pairs are only suggested. The only exceptions are user-approved `=` declaration tables and imports | `common/06_table-engine.ts`, `typescript/13_grid-kinds.ts` `minRows` |
+| 5 | **Idempotent.** Running twice gives the same result | per-language alignment tests (`test/lang-harness.ts`) |
+| 6 | **Only relative placement is stored.** Width is always the minimum that table needs, and tables never share widths | `common/06_table-engine.ts` |
+| 7 | **Deterministic.** The same input and config give the same result. There is no LLM and no similarity search on the check/fix path. An LLM is used only to read guidance or to pre-sort the review queue | design rule (no reproduction test) |
+| 8 | **Only humans approve.** Evidence never becomes a rule by itself. Agents only investigate and propose | read-only agents: `test/plugin-contract.test.ts` · approval flow: not implemented |
+| 9 | **Layer priority:** safety > project > user > preset > base. Nothing overrides safety | not implemented (M1.8 S3–S5) |
+| 10 | **Single source, thin adapters.** The engine, grammar and conventions live in one place; hosts differ only in install location and manifest. The result JSON and pattern keys are versioned public contracts | `common/24_result-json.ts`, `common/02_signature.ts` |
+| 11 | **Runs last, after the formatter.** The canonical form of a file is `boxbox(formatter(file))`, and rerunning must not change it | not implemented (M2) |
+
+## 6. What this document does not do
+
+- It does not define concrete patterns, roles or rules → grammar (`grammar.md`), conventions (`presets/`, `.boxbox/rules/`).
+- It does not list the order in which tools are called → `SKILL.md`.
+- It does not describe the product structure or roadmap → `docs/development/design.md`.
+
+## 7. How to change it
+
+1. First write the reason and evidence for the change in `docs/development/plan.md`.
+2. A maintainer approves it.
+3. When an invariant changes, change the code and tests that enforce it in the same change.
+4. When the three core lines change, change the copies (`SKILL.md`, the marked section of the user's `AGENTS.md`) in the same change.