@brunobracaioli/aibrain 0.4.0-beta.13 → 0.4.0-beta.14

package/README.md

@@ -30,6 +30,19 @@ roles. Nothing is written to `~/.codex`, `~/.agents` or the project, and the
 session's folder is deleted on exit. An older Codex starts without the pack and
 says `codex_outdated`.
 
+`aisac init [dir]` (licensed accounts, client `0.4.0-beta.14` or later) writes the
+AISAC skeleton into a new or existing project: `CLAUDE.md`, `AGENTS.md`,
+`NOTES.example.md`, the `docs/` tree with its templates, a Claude Code rules file,
+a CI workflow with pinned actions, Dependabot, `.gitignore` and the workloop
+template. The templates travel inside the licensed pack, fetched and verified like
+a launch; the command writes only files that are missing, never follows a symbolic
+link, never touches `.git/` and prints every file it wrote or skipped. Options:
+`--stack node|python|none` (otherwise detected from `package.json`, `pyproject.toml`
+or `requirements.txt`), `--lang pt-BR|en`, `--dry-run`, `--json`. Exit codes: `0`
+when every file exists or was written, `1` for a license, pack or write failure
+(nothing is written before the pack is verified), `2` for a usage error. Until the
+pack carries the templates, the command says so and writes nothing.
+
 Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
 `aisac-guardrails`.
 - **Default on:** `secrets-guard` refuses secret files by name. Four more hooks

package/dist/claude-observation.mjs

@@ -16,7 +16,7 @@ export const MAX_LOG_FILES = 3;
 const LOCK_WAIT_MS = 250;
 const LOCK_STALE_MS = 30_000;
 const ADMISSION_MS = 60 * 60 * 1000;
-export const ADAPTER_VERSION = '0.4.0-beta.13';
+export const ADAPTER_VERSION = '0.4.0-beta.14';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);

package/dist/cli.mjs

@@ -37,13 +37,14 @@ import {
   resolvePackLocale,
   writeStoredLocale,
 } from './engineering-pack.mjs';
+import { initCommand } from './engineering-init.mjs';
 import { extensionsSummary, hooksCommand, mcpCommand } from './extensions-cli.mjs';
 import { sessionServers } from './mcp-servers.mjs';
 import { anyFormatter } from './guardrails/format.mjs';
 import { readCodexGuardrails } from './guardrails-plugin.mjs';
 import { codexHooksStatus, supportsCodexHooks } from './codex-hooks.mjs';
 
-const VERSION = '0.4.0-beta.13';
+const VERSION = '0.4.0-beta.14';
 // The command is `aisac`; `aibrain` is an alias installed from the same entry.
 const COMMAND = 'aisac';
 const ENDPOINT = 'https://mcp.ai-brain.aisac.cloud/mcp';
@@ -52,7 +53,7 @@ const LEGACY_DISCLOSURE_VERSION = 'aibrain-paid-context-v1-2026-10-09';
 
 function usage() {
   console.log(
-    `${COMMAND} ${VERSION}\n\nUsage:\n  ${COMMAND} setup [--client claude|codex|both] [--context-profile upstream|conservative]\n    [--compact-at 1..95] [--keep-threshold 0..1] [--preserve-recent 1..100]\n    [--min-reduction 0..1] [--truncate-head-chars 0..4096]\n    [--max-state-tokens 1000..25000] [--max-request-tokens 1000..30000]\n    [--tool-policy compatible|read_only] [--goal TEXT]\n  ${COMMAND} doctor [--json]\n  ${COMMAND} status [--json]\n  ${COMMAND} disable\n  ${COMMAND} setup --undo\n  ${COMMAND} claude [-- native-args...]\n  ${COMMAND} codex [-- native-args...]\n\nPolicy notes:\n  Automatic monitoring asks for compaction at compact-at percent; state/request\n  limits are estimated upper bounds and do not override server quotas.\n  min-reduction, truncate-head-chars and tool-policy apply only to Claude;\n  Codex keeps native compaction and same-session recovery.`,
+    `${COMMAND} ${VERSION}\n\nUsage:\n  ${COMMAND} setup [--client claude|codex|both] [--context-profile upstream|conservative]\n    [--compact-at 1..95] [--keep-threshold 0..1] [--preserve-recent 1..100]\n    [--min-reduction 0..1] [--truncate-head-chars 0..4096]\n    [--max-state-tokens 1000..25000] [--max-request-tokens 1000..30000]\n    [--tool-policy compatible|read_only] [--goal TEXT]\n  ${COMMAND} doctor [--json]\n  ${COMMAND} status [--json]\n  ${COMMAND} disable\n  ${COMMAND} setup --undo\n  ${COMMAND} claude [-- native-args...]\n  ${COMMAND} codex [-- native-args...]\n  ${COMMAND} init [dir] [--lang pt-BR|en] [--stack node|python|none] [--dry-run] [--json]\n\nPolicy notes:\n  Automatic monitoring asks for compaction at compact-at percent; state/request\n  limits are estimated upper bounds and do not override server quotas.\n  min-reduction, truncate-head-chars and tool-policy apply only to Claude;\n  Codex keeps native compaction and same-session recovery.`,
   );
   console.log(
     'Clients: setup without --client configures the clients installed on PATH (Claude Code, Codex, or both).',
@@ -66,6 +67,9 @@ function usage() {
   console.log(
     'AISAC Engineering: `aisac claude` and `aisac codex` (Codex 0.164+) load the licensed method; setup --lang pt-BR|en picks its language (before the first setup it runs the full setup); setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
   );
+  console.log(
+    'Project skeleton: `aisac init [dir]` (licensed accounts) writes the AISAC skeleton from the pack into a new or existing project, only the files that are missing; `--dry-run` lists them, `--stack` picks node|python|none when detection is not enough.',
+  );
   console.log(
     'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` or `aisac codex` session.',
   );
@@ -845,6 +849,14 @@ async function main(argv) {
   }
   if (command === 'hooks') return hooksCommand(rest);
   if (command === 'mcp') return mcpCommand(rest);
+  if (command === 'init')
+    return initCommand(rest, {
+      packageRoot: PACKAGE_ROOT,
+      readConfig,
+      stateRoot,
+      cwd: process.cwd(),
+      env: process.env,
+    });
   if (command === 'disable') {
     if (rest.length > 0) throw new Error('disable_does_not_accept_options');
     return removeOwnedSetup();
@@ -897,5 +909,7 @@ main(cliArgs).catch((error) => {
     const guide = /** @type {{ guide?: unknown }} */ (error ?? {}).guide;
     if (typeof guide === 'string') console.error(`\n${guide}`);
   }
-  process.exitCode = 1;
+  // Usage errors of `aisac init` exit 2 (spec FR3); everything else exits 1.
+  const exitCode = /** @type {{ exitCode?: unknown }} */ (error ?? {}).exitCode;
+  process.exitCode = exitCode === 2 ? 2 : 1;
 });

package/dist/engineering-init.mjs

@@ -0,0 +1,613 @@
+// @ts-check
+
+/**
+ * `aisac init` (spec aisac-engineering-init, ADR-0053, wave E5c): the AISAC
+ * skeleton written into the user's project from the licensed pack's `init/`
+ * templates.
+ *
+ * A template is one pack file under `init/` whose front matter names the
+ * target path and the stack, and whose body holds exactly one fenced code
+ * block: the fenced lines are the file. Only that body is written, so the
+ * per-account watermark the server adds to every front matter never reaches
+ * a repository. Only missing files are written, with exclusive creates, never
+ * through a symbolic link and never under `.git/`. The command fetches and
+ * verifies the pack with the same code path as a launch; nothing is written
+ * before the pack is verified, and nothing is written outside the directory
+ * the user named.
+ */
+
+import { lstat, mkdir, open, realpath, stat } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+import {
+  INIT_PREFIX,
+  isPackLocale,
+  obtainPack,
+  packNotice,
+  readStoredLocale,
+  resolvePackLocale,
+  splitFrontMatter,
+} from './engineering-pack.mjs';
+import { isRecord } from './engineering.mjs';
+
+export const INIT_STACKS = /** @type {const} */ (['node', 'python', 'none']);
+const TEMPLATE_STACKS = new Set([...INIT_STACKS, 'all']);
+const TEMPLATE_PATH = /^init\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\.md$/u;
+const TEMPLATE_KEYS = new Set(['name', 'description', 'target', 'stack', 'aisac_watermark']);
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_TARGET_LENGTH = 200;
+const TARGET_CHARACTERS = /^[A-Za-z0-9._/-]+$/u;
+const FORBIDDEN_SEGMENTS = new Set(['.', '..', '.git']);
+const OPENING_FENCE = /^(`{3,})([^`]*)$/u;
+const CLOSING_FENCE = /^(`{3,})[ \t]*$/u;
+const WATERMARK_KEY = 'aisac_watermark';
+const PROJECT_NAME = /^[A-Za-z0-9._-]{1,64}$/u;
+const PROJECT_NAME_TOKEN = '{{project_name}}';
+const DEFAULT_PROJECT_NAME = 'project';
+/** YAML and `.gitignore` templates are byte-identical across locales and carry no token (spec D7, D8). */
+const CONFIGURATION_TARGET = /(?:\.ya?ml|\.gitignore)$/u;
+const DIRECTORY_MODE = 0o755;
+const FILE_MODE = 0o644;
+const NODE_MANIFEST = 'package.json';
+const PYTHON_MANIFESTS = ['pyproject.toml', 'requirements.txt'];
+const CLAUDE_MEMORY_FILE = 'CLAUDE.md';
+const USAGE_EXIT_CODE = 2;
+const UPDATE_COMMAND = 'npm install -g @aisac/cli@beta';
+
+/** @typedef {(typeof INIT_STACKS)[number]} InitStack */
+/** @typedef {InitStack | 'all'} TemplateStack */
+/** @typedef {import('./engineering-pack.mjs').PackLocale} PackLocale */
+/**
+ * @typedef {{
+ *   path: string,
+ *   name: string,
+ *   description: string,
+ *   target: string,
+ *   stack: TemplateStack,
+ *   body: string
+ * }} InitTemplate
+ */
+/** @typedef {'init_path' | 'init_front_matter' | 'init_target' | 'init_body'} InitTemplateReason */
+/** @typedef {'wrote' | 'skipped' | 'failed'} InitOutcome */
+/** @typedef {{ target: string, outcome: InitOutcome, reason: string | null }} InitEntry */
+/**
+ * @typedef {{
+ *   directory: string,
+ *   entries: InitEntry[],
+ *   wrote: string[],
+ *   skipped: { target: string, reason: string }[],
+ *   failed: { target: string, reason: string }[]
+ * }} InitResult
+ */
+
+/** A template the server should never have served; the whole run stops. */
+export class InitTemplateError extends Error {
+  /** @param {InitTemplateReason} reason @param {string} path */
+  constructor(reason, path) {
+    super(`init_template_invalid:${reason}:${path}`);
+    this.reason = reason;
+    this.path = path;
+  }
+}
+
+/** @param {string} code */
+function usageError(code) {
+  const error = new Error(code);
+  Object.defineProperty(error, 'exitCode', { value: USAGE_EXIT_CODE });
+  return error;
+}
+
+/** @param {unknown} value @returns {value is InitStack} */
+export function isInitStack(value) {
+  return typeof value === 'string' && INIT_STACKS.includes(/** @type {InitStack} */ (value));
+}
+
+/**
+ * Relative, `[A-Za-z0-9._/-]`, at most 200 characters, no empty, `.`, `..` or
+ * `.git` segment (spec FR2). A leading dot inside a segment is fine (`.github`).
+ * @param {unknown} target
+ * @returns {target is string}
+ */
+export function isValidInitTarget(target) {
+  if (typeof target !== 'string' || target.length === 0 || target.length > MAX_TARGET_LENGTH)
+    return false;
+  if (!TARGET_CHARACTERS.test(target)) return false;
+  return target
+    .split('/')
+    .every((segment) => segment.length > 0 && !FORBIDDEN_SEGMENTS.has(segment.toLowerCase()));
+}
+
+/**
+ * The one fenced block of a template body, as file content: its lines, each
+ * ended by a newline; an empty block is an empty file. Anything outside the
+ * block is the author's note. A longer outer fence keeps inner fences as
+ * content, so a template can carry Markdown with code blocks.
+ * @param {string} markdown
+ * @param {string} path
+ */
+function fencedBody(markdown, path) {
+  /** @type {number | null} */
+  let fence = null;
+  /** @type {string[] | null} */
+  let content = null;
+  let closed = false;
+  for (const line of markdown.split('\n')) {
+    if (fence === null) {
+      const opening = OPENING_FENCE.exec(line);
+      if (opening === null) continue;
+      if (closed) throw new InitTemplateError('init_body', path);
+      fence = opening[1]?.length ?? 0;
+      content = [];
+      continue;
+    }
+    const closing = CLOSING_FENCE.exec(line);
+    if (closing !== null && (closing[1]?.length ?? 0) >= fence) {
+      fence = null;
+      closed = true;
+      continue;
+    }
+    content?.push(line);
+  }
+  if (fence !== null || !closed || content === null) throw new InitTemplateError('init_body', path);
+  if (content.some((line) => line.includes(WATERMARK_KEY)))
+    throw new InitTemplateError('init_body', path);
+  return content.length === 0 ? '' : `${content.join('\n')}\n`;
+}
+
+/**
+ * Parse one `init/<name>.md` pack file (spec FR2). The server validates the
+ * same rules before serving; this is the second layer.
+ * @param {{ path: string, content: string }} file
+ * @returns {InitTemplate}
+ */
+export function parseInitTemplate(file) {
+  const stem = TEMPLATE_PATH.exec(file.path)?.[1];
+  if (stem === undefined) throw new InitTemplateError('init_path', file.path);
+  const parsed = splitFrontMatter(file.content);
+  if (parsed === null) throw new InitTemplateError('init_front_matter', file.path);
+  const { values, body } = parsed;
+  for (const key of values.keys()) {
+    if (!TEMPLATE_KEYS.has(key)) throw new InitTemplateError('init_front_matter', file.path);
+  }
+  const name = values.get('name');
+  const description = values.get('description');
+  const stack = values.get('stack') ?? 'all';
+  if (
+    name !== stem ||
+    description === undefined ||
+    description.length === 0 ||
+    description.length > MAX_DESCRIPTION_LENGTH ||
+    description === '>' ||
+    description === '|' ||
+    !TEMPLATE_STACKS.has(stack)
+  )
+    throw new InitTemplateError('init_front_matter', file.path);
+  const target = values.get('target');
+  if (!isValidInitTarget(target)) throw new InitTemplateError('init_target', file.path);
+  return {
+    path: file.path,
+    name,
+    description,
+    target,
+    stack: /** @type {TemplateStack} */ (stack),
+    body: fencedBody(body, file.path),
+  };
+}
+
+/** @param {string} left @param {string} right */
+function compareTargets(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/**
+ * Every `init/` template of a verified pack, in sorted target order. Two
+ * templates may share a target only with different stacks, neither `all`; no
+ * target may be a directory of another.
+ * @param {readonly { path: string, content: string }[]} files
+ * @returns {InitTemplate[]}
+ */
+export function loadInitTemplates(files) {
+  const templates = files
+    .filter((file) => file.path.startsWith(INIT_PREFIX))
+    .map((file) => parseInitTemplate(file))
+    .sort(
+      (left, right) =>
+        compareTargets(left.target, right.target) || compareTargets(left.stack, right.stack),
+    );
+  /** @type {Map<string, InitTemplate[]>} */
+  const byTarget = new Map();
+  const directories = new Set();
+  for (const template of templates) {
+    const segments = template.target.split('/');
+    for (let depth = 1; depth < segments.length; depth += 1)
+      directories.add(segments.slice(0, depth).join('/'));
+    const sharing = byTarget.get(template.target) ?? [];
+    for (const other of sharing) {
+      if (other.stack === template.stack || other.stack === 'all' || template.stack === 'all')
+        throw new InitTemplateError('init_target', template.path);
+    }
+    sharing.push(template);
+    byTarget.set(template.target, sharing);
+  }
+  for (const template of templates) {
+    if (directories.has(template.target)) throw new InitTemplateError('init_target', template.path);
+  }
+  return templates;
+}
+
+/**
+ * The templates of one stack: its own plus the shared ones.
+ * @param {readonly InitTemplate[]} templates
+ * @param {InitStack} stack
+ */
+export function selectTemplates(templates, stack) {
+  return templates.filter((template) => template.stack === 'all' || template.stack === stack);
+}
+
+/** @param {string} path */
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `node` from `package.json`, `python` from `pyproject.toml` or
+ * `requirements.txt`, `none` without either, `ambiguous` with both (spec D6).
+ * A missing directory has no stack.
+ * @param {string} directory
+ * @returns {Promise<InitStack | 'ambiguous'>}
+ */
+export async function detectStack(directory) {
+  const [node, ...python] = await Promise.all([
+    isFile(join(directory, NODE_MANIFEST)),
+    ...PYTHON_MANIFESTS.map((manifest) => isFile(join(directory, manifest))),
+  ]);
+  const hasPython = python.some(Boolean);
+  if (node && hasPython) return 'ambiguous';
+  if (node) return 'node';
+  return hasPython ? 'python' : 'none';
+}
+
+/**
+ * The directory's base name when it fits the token charset, else `project`
+ * (spec D7).
+ * @param {string} directory
+ */
+export function projectNameOf(directory) {
+  const name = basename(directory);
+  return PROJECT_NAME.test(name) ? name : DEFAULT_PROJECT_NAME;
+}
+
+/**
+ * The file content for one template: the fenced body with `{{project_name}}`
+ * replaced in text templates; YAML and `.gitignore` are written as they are.
+ * @param {InitTemplate} template
+ * @param {string} projectName
+ */
+export function renderTemplate(template, projectName) {
+  return CONFIGURATION_TARGET.test(template.target)
+    ? template.body
+    : template.body.replaceAll(PROJECT_NAME_TOKEN, projectName);
+}
+
+/** @param {unknown} error */
+function errorCode(error) {
+  return isRecord(error) && typeof error.code === 'string' ? error.code : 'write_failed';
+}
+
+/**
+ * Create the missing parents of a target without following links. A
+ * symbolic link on the way skips the file; a non-directory fails it.
+ * @param {string} base
+ * @param {readonly string[]} segments
+ * @param {boolean} dryRun
+ * @returns {Promise<{ outcome: 'ok' } | { outcome: 'skipped' | 'failed', reason: string }>}
+ */
+async function ensureParents(base, segments, dryRun) {
+  let current = base;
+  for (const segment of segments) {
+    current = join(current, segment);
+    let entry = await lstat(current).catch(() => null);
+    if (entry === null) {
+      if (dryRun) continue;
+      try {
+        await mkdir(current, { mode: DIRECTORY_MODE });
+      } catch (error) {
+        if (errorCode(error) !== 'EEXIST') return { outcome: 'failed', reason: errorCode(error) };
+      }
+      entry = await lstat(current).catch(() => null);
+      if (entry === null) return { outcome: 'failed', reason: 'parent_missing' };
+    }
+    if (entry.isSymbolicLink()) return { outcome: 'skipped', reason: 'symlink' };
+    if (!entry.isDirectory()) return { outcome: 'failed', reason: 'parent_not_directory' };
+  }
+  return { outcome: 'ok' };
+}
+
+/**
+ * Write the selected templates into the directory: missing files only,
+ * exclusive creates, `0644` files and `0755` directories, sorted target
+ * order, each file reported once. With `dryRun` nothing is created and the
+ * files that would be written are listed as written.
+ * @param {{ directory: string, templates: readonly InitTemplate[], projectName: string, dryRun: boolean }} input
+ * @returns {Promise<InitResult>}
+ */
+export async function applySkeleton(input) {
+  const base = input.dryRun
+    ? await realpath(input.directory).catch(() => resolve(input.directory))
+    : await realpath(input.directory);
+  /** @type {InitEntry[]} */
+  const entries = [];
+  for (const template of input.templates) {
+    const segments = template.target.split('/');
+    const full = resolve(base, ...segments);
+    if (!full.startsWith(`${base}${sep}`)) {
+      entries.push({ target: template.target, outcome: 'failed', reason: 'target_escape' });
+      continue;
+    }
+    const parents = await ensureParents(base, segments.slice(0, -1), input.dryRun);
+    if (parents.outcome !== 'ok') {
+      entries.push({ target: template.target, outcome: parents.outcome, reason: parents.reason });
+      continue;
+    }
+    const existing = await lstat(full).catch(() => null);
+    if (existing !== null) {
+      entries.push({
+        target: template.target,
+        outcome: 'skipped',
+        reason: existing.isSymbolicLink() ? 'symlink' : 'exists',
+      });
+      continue;
+    }
+    if (input.dryRun) {
+      entries.push({ target: template.target, outcome: 'wrote', reason: null });
+      continue;
+    }
+    try {
+      const handle = await open(full, 'wx', FILE_MODE);
+      try {
+        await handle.writeFile(renderTemplate(template, input.projectName), 'utf8');
+      } finally {
+        await handle.close();
+      }
+      entries.push({ target: template.target, outcome: 'wrote', reason: null });
+    } catch (error) {
+      const code = errorCode(error);
+      entries.push(
+        code === 'EEXIST'
+          ? { target: template.target, outcome: 'skipped', reason: 'exists' }
+          : { target: template.target, outcome: 'failed', reason: code },
+      );
+    }
+  }
+  return {
+    directory: base,
+    entries,
+    wrote: entries.filter((entry) => entry.outcome === 'wrote').map((entry) => entry.target),
+    skipped: entries
+      .filter((entry) => entry.outcome === 'skipped')
+      .map((entry) => ({ target: entry.target, reason: entry.reason ?? 'exists' })),
+    failed: entries
+      .filter((entry) => entry.outcome === 'failed')
+      .map((entry) => ({ target: entry.target, reason: entry.reason ?? 'write_failed' })),
+  };
+}
+
+/**
+ * The next steps after a run, in the pack locale (spec FR3).
+ * @param {PackLocale} locale
+ * @param {InitResult} result
+ */
+export function nextSteps(locale, result) {
+  const pt = locale === 'pt-BR';
+  const claudeKept = result.skipped.some(
+    (entry) => entry.target === CLAUDE_MEMORY_FILE && entry.reason === 'exists',
+  );
+  return [
+    pt
+      ? 'Copie NOTES.example.md para NOTES.md (o .gitignore já o exclui) e mantenha-o atualizado.'
+      : 'Copy NOTES.example.md to NOTES.md (already in .gitignore) and keep it current.',
+    pt
+      ? 'Preencha os marcadores [CUSTOMIZE] de CLAUDE.md, AGENTS.md e .claude/rules/ na primeira sessão; o seu agente pode fazer isso.'
+      : 'Fill the [CUSTOMIZE] markers in CLAUDE.md, AGENTS.md and .claude/rules/ in the first session; your agent can do it.',
+    pt
+      ? 'Rode aisac claude ou aisac codex nesta pasta: o método chega com a sessão.'
+      : 'Run aisac claude or aisac codex in this folder: the method arrives with the session.',
+    pt
+      ? 'Leia docs/README.md para o mapa da documentação.'
+      : 'Read docs/README.md for the documentation map.',
+    ...(claudeKept
+      ? [
+          pt
+            ? 'CLAUDE.md já existia e ficou como estava; peça à skill aisac-method para incorporar o método nele.'
+            : 'CLAUDE.md already existed and was left as is; ask the aisac-method skill to fold the method into it.',
+        ]
+      : []),
+  ];
+}
+
+/**
+ * The human report: one line per file in target order, a summary, the next steps.
+ * @param {{ result: InitResult, locale: PackLocale, stack: InitStack, packVersion: string, dryRun: boolean }} input
+ */
+export function initReport(input) {
+  const pt = input.locale === 'pt-BR';
+  const lines = input.result.entries.map((entry) => {
+    switch (entry.outcome) {
+      case 'wrote':
+        return input.dryRun
+          ? `${pt ? 'gravaria' : 'would write'} ${entry.target}`
+          : `${pt ? 'gravado' : 'wrote'} ${entry.target}`;
+      case 'skipped':
+        return `${pt ? 'pulado' : 'skipped'} ${entry.target} (${entry.reason})`;
+      default:
+        return `${pt ? 'falhou' : 'failed'} ${entry.target} (${entry.reason})`;
+    }
+  });
+  const counts = pt
+    ? `${input.result.wrote.length} ${input.dryRun ? 'a gravar' : 'gravados'}, ${input.result.skipped.length} pulados, ${input.result.failed.length} com falha`
+    : `${input.result.wrote.length} ${input.dryRun ? 'to write' : 'written'}, ${input.result.skipped.length} skipped, ${input.result.failed.length} failed`;
+  lines.push(
+    `aisac init: ${counts} (stack ${input.stack}, ${input.locale}, pack ${input.packVersion}) ${pt ? 'em' : 'in'} ${input.result.directory}`,
+  );
+  if (!input.dryRun && input.result.failed.length === 0) {
+    lines.push(pt ? 'Próximos passos:' : 'Next steps:');
+    for (const [index, step] of nextSteps(input.locale, input.result).entries())
+      lines.push(`  ${index + 1}. ${step}`);
+  }
+  return lines;
+}
+
+/**
+ * @typedef {{
+ *   dir: string | undefined,
+ *   lang: PackLocale | undefined,
+ *   stack: InitStack | undefined,
+ *   dryRun: boolean,
+ *   json: boolean
+ * }} InitArguments
+ */
+
+/**
+ * `aisac init [dir] [--lang pt-BR|en] [--stack node|python|none] [--dry-run] [--json]`.
+ * Usage errors exit 2.
+ * @param {readonly string[]} args
+ * @returns {InitArguments}
+ */
+export function parseInitArguments(args) {
+  /** @type {InitArguments} */
+  const parsed = { dir: undefined, lang: undefined, stack: undefined, dryRun: false, json: false };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = /** @type {string} */ (args[index]);
+    if (argument === '--dry-run' || argument === '--json') {
+      const key = argument === '--json' ? 'json' : 'dryRun';
+      if (parsed[key]) throw usageError(`duplicate_option:${argument}`);
+      parsed[key] = true;
+    } else if (argument === '--lang' || argument === '--stack') {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith('-'))
+        throw usageError(`option_value_required:${argument}`);
+      const key = argument === '--lang' ? 'lang' : 'stack';
+      if (parsed[key] !== undefined) throw usageError(`duplicate_option:${argument}`);
+      if (key === 'lang') {
+        if (!isPackLocale(value)) throw usageError('invalid_lang');
+        parsed.lang = value;
+      } else {
+        if (!isInitStack(value)) throw usageError('invalid_stack');
+        parsed.stack = value;
+      }
+      index += 1;
+    } else if (argument.startsWith('-') || parsed.dir !== undefined) {
+      throw usageError('unknown_option');
+    } else {
+      parsed.dir = argument;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * @typedef {{
+ *   packageRoot: string,
+ *   readConfig: () => Promise<unknown>,
+ *   stateRoot: () => string,
+ *   cwd?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   fetchImpl?: typeof fetch,
+ *   log?: (line: string) => void,
+ *   warn?: (line: string) => void
+ * }} InitDependencies
+ */
+
+/** @param {unknown} config @returns {{ endpoint: string, token: string }} */
+function accountOf(config) {
+  if (
+    !isRecord(config) ||
+    typeof config.endpoint !== 'string' ||
+    typeof config.token !== 'string' ||
+    config.token.length === 0
+  )
+    throw new Error('setup_required');
+  return { endpoint: config.endpoint, token: config.token };
+}
+
+/**
+ * The command. Throws with the error code as message; usage errors carry
+ * `exitCode` 2, everything else exits 1 through the CLI's handler.
+ * @param {readonly string[]} args
+ * @param {InitDependencies} deps
+ */
+export async function initCommand(args, deps) {
+  const log = deps.log ?? ((line) => console.log(line));
+  const warn = deps.warn ?? ((line) => console.error(line));
+  const options = parseInitArguments(args);
+  const directory = resolve(deps.cwd ?? process.cwd(), options.dir ?? '.');
+  const existing = await stat(directory).catch(() => null);
+  if (existing !== null && !existing.isDirectory()) throw usageError('dir_not_directory');
+  const detected = options.stack ?? (existing === null ? 'none' : await detectStack(directory));
+  if (detected === 'ambiguous') throw usageError('stack_ambiguous');
+  const stack = detected;
+  const account = accountOf(await deps.readConfig());
+  const locale =
+    options.lang ?? resolvePackLocale(await readStoredLocale(deps.stateRoot()), deps.env);
+  const outcome = await obtainPack({
+    endpoint: account.endpoint,
+    token: account.token,
+    locale,
+    packageRoot: deps.packageRoot,
+    ...(deps.fetchImpl === undefined ? {} : { fetchImpl: deps.fetchImpl }),
+  });
+  if (outcome.outcome !== 'loaded') {
+    const notice = packNotice(outcome, locale);
+    if (notice !== null) warn(notice);
+    switch (outcome.outcome) {
+      case 'inactive':
+        throw new Error('license_inactive');
+      case 'not_offered':
+        throw new Error('engineering_not_offered');
+      case 'unavailable':
+        throw new Error(`pack_unavailable:${outcome.reason}`);
+      default:
+        throw new Error(`pack_rejected:${outcome.reason}`);
+    }
+  }
+  const templates = selectTemplates(loadInitTemplates(outcome.pack.files), stack);
+  if (templates.length === 0) {
+    warn(
+      locale === 'pt-BR'
+        ? `AISAC Engineering: o pacote ainda não traz os modelos do init; atualize o aisac (${UPDATE_COMMAND}) ou tente mais tarde.`
+        : `AISAC Engineering: the pack carries no init templates yet; update aisac (${UPDATE_COMMAND}) or try again later.`,
+    );
+    throw new Error('init_templates_missing');
+  }
+  if (existing === null && !options.dryRun)
+    await mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
+  const result = await applySkeleton({
+    directory,
+    templates,
+    projectName: projectNameOf(await realpath(directory).catch(() => directory)),
+    dryRun: options.dryRun,
+  });
+  const packVersion = outcome.pack.packVersion;
+  if (options.json) {
+    log(
+      JSON.stringify({
+        dir: result.directory,
+        locale,
+        stack,
+        packVersion,
+        dryRun: options.dryRun,
+        wrote: result.wrote,
+        skipped: result.skipped,
+        failed: result.failed,
+        nextSteps: nextSteps(locale, result),
+      }),
+    );
+  } else {
+    for (const line of initReport({ result, locale, stack, packVersion, dryRun: options.dryRun }))
+      log(line);
+  }
+  if (result.failed.length > 0) throw new Error('init_write_failed');
+}

package/dist/engineering-pack.mjs

@@ -94,6 +94,11 @@ const FORBIDDEN_FRONT_MATTER_KEYS = new Set([
 const PLUGIN_NAME = 'aisac-engineering';
 const PLUGIN_LICENSE = 'LicenseRef-AISAC-Engineering';
 const PACK_DIRECTORY = 'engineering';
+/**
+ * `aisac init` templates (spec aisac-engineering-init D2, E5c): pack files that
+ * never reach a session. Only `engineering-init.mjs` reads them.
+ */
+export const INIT_PREFIX = 'init/';
 const OUTPUT_STYLES_PREFIX = 'output-styles/';
 const SKILLS_DIRECTORY = 'skills';
 const AGENT_FILE = /^agents\/([a-z][a-z0-9-]{0,63})\.md$/u;
@@ -534,7 +539,8 @@ const PLUGIN_DESCRIPTION = {
 
 /**
  * Write the pack files into `engineering/` of the launch's private directory:
- * `0700` directories, `0600` files, exclusive creation, contained paths.
+ * `0700` directories, `0600` files, exclusive creation, contained paths. The
+ * `init/` templates stay out: they are for `aisac init`, not for a session.
  * @param {VerifiedPack} pack
  * @param {string} launchDirectory
  * @returns {Promise<string>} the pack root
@@ -544,6 +550,7 @@ async function writePackFiles(pack, launchDirectory) {
   await mkdir(base, { mode: 0o700 });
   for (const file of pack.files) {
     if (!isValidPackPath(file.path)) throw new Error('pack_path_invalid');
+    if (file.path.startsWith(INIT_PREFIX)) continue;
     const target = resolve(base, ...file.path.split('/'));
     if (!target.startsWith(`${base}${sep}`)) throw new Error('pack_path_escape');
     await mkdir(dirname(target), { recursive: true, mode: 0o700 });

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.4.0-beta.13",
+  "version": "0.4.0-beta.14",
   "type": "module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.4.0-beta.13",
+  "version": "0.4.0-beta.14",
   "private": false,
   "description": "AISAC client for Claude Code and Codex: AI Brain memory, context management and AISAC Engineering",
   "license": "UNLICENSED",