@aiwg/cli 2026.9.3 → 2026.9.5

package/dist/src/cli/handlers/sessions.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, realpathSync, statSync, } from 'node:fs';
 import { dirname, isAbsolute, resolve, } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SESSION_PROVIDER_IDS, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, } from '../../sessions/index.js';
+import { CLAUDE_ADAPTER_VERSION, ClaudeSessionAdapter, CODEX_ADAPTER_VERSION, CodexSessionAdapter, COPILOT_ADAPTER_VERSION, CopilotSessionAdapter, CURSOR_ADAPTER_VERSION, CursorSessionAdapter, FACTORY_ADAPTER_VERSION, FactorySessionAdapter, HERMES_ADAPTER_VERSION, HermesSessionAdapter, OPENCODE_ADAPTER_VERSION, OpenCodeSessionAdapter, OPENCLAW_ADAPTER_VERSION, OpenClawSessionAdapter, OPENHUMAN_ADAPTER_VERSION, OpenHumanSessionAdapter, PI_ADAPTER_VERSION, PiSessionAdapter, DEEPSEEK_HARNESS_ADAPTER_VERSION, DeepSeekHarnessSessionAdapter, OmpSessionAdapter, OMP_ADAPTER_VERSION, WARP_ADAPTER_VERSION, WarpSessionAdapter, DEVIN_DESKTOP_ADAPTER_VERSION, DevinDesktopSessionAdapter, CandidateExtractionService, GENERIC_ADAPTER_VERSION, GenericSessionInterchangeAdapter, IncrementalSessionImporter, ImportLeaseContentionError, FilesystemMemoryDestination, FilesystemPromotionDispositionCoordinator, MemoryPromotionGateway, SESSION_CONTRACT_VERSION, SESSION_PROVIDER_IDS, SessionContractError, SessionRepository, SessionSourceSchema, StructuralCandidateExtractor, resolveMemoryConsumerManifest, assertSessionProviderId, acquireImportLease, defaultDiscoveryManifestPath, discoverWorkspaceHistories, deriveSessionTimeline, importDiscoveryManifest, previewDiscoveryImport, publicDiscoveryManifest, readDiscoveryManifest, redactSourceLocator, sha256, parseTimelineGap, writeDiscoveryManifest, } from '../../sessions/index.js';
 const JSON_CONTRACT_VERSION = '1.0.0';
 async function createLineMemoryPromotionDestination(projectRoot, manifestPath) {
     const modulePath = resolve(dirname(manifestPath), 'commands', 'line-memory.mjs');
@@ -55,6 +55,7 @@ Options:
   --provider-home <path>  Override the provider home root (testing/portable homes)
   --codex-root <path>  Explicitly authorize a shared Codex sessions/export root
   --omp-root <path>  Explicitly authorize an OMP profile sessions root
+  --dsh-root <path>  Explicitly authorize a DeepSeek Harness sessions root
   --confirm, --yes  Confirm a persistent discovered batch import
   --lock-wait-ms <n>  Maximum import-lease wait (default 5000)
   --inactivity-threshold <duration>  Historical inactivity threshold (default 24h)
@@ -63,13 +64,39 @@ Options:
   --consumer <id> Select a named memory consumer for promotion
   --workspace <id>, --tag <tag>, --limit <n>, --cursor <n>
   --page-size <n>  Extraction scan page size (default 250, maximum 500)
-  --max-documents <n>  Explicit extraction safety limit; returns a partial receipt`;
+  --max-documents <n>  Explicit extraction safety limit; returns a partial receipt
+
+Search filters:
+  --date-from <rfc3339>, --date-to <rfc3339>
+  --participant <actor>, --model <id>, --role <role>, --tool <name>
+  --entity <entity>, --sensitivity <class>, --extraction-state <state>
+  --control-events exclude|include|only (default: exclude)
+  Query syntax: FTS5 terms, quoted phrases, prefixes, AND/OR/NOT
+  Follow the opaque nextCursor with the same query and filters
+
+Analytics / forensics:
+  --session <id>, --date-from <rfc3339>, --date-to <rfc3339>
+  --actor <id>, --participant <id>, --tool <name>, --status <status>
+  --provider <id>, --tag <tag>, --sensitivity <class>, --extraction-state <state>
+  --group-by tool|session|provider, --limit <1..5000>
+  --authorize-forensics  Required for each authorized forensic invocation
+  --markdown      Render a sanitized forensic timeline table`;
+function printHelp(ctx, exitCode = EXIT.ok) {
+    if (ctx.args.includes('--json'))
+        emit(envelope('sessions.help', 'ok', { usage: HELP }, null));
+    else
+        console.log(HELP);
+    return { exitCode };
+}
 export const sessionsHandler = {
     id: 'sessions',
     name: 'Sessions',
     description: 'Manage the normalized session catalog (the singular `session` command remains the launcher)',
     category: 'project',
     aliases: [],
+    async help(ctx) {
+        return printHelp(ctx);
+    },
     async execute(ctx) {
         const json = ctx.args.includes('--json');
         let parsed;
@@ -86,11 +113,8 @@ export const sessionsHandler = {
             return { exitCode: normalized.exitCode, message: normalized.error.message };
         }
         if (!parsed.command || parsed.flags.has('--help') || parsed.flags.has('-h')) {
-            if (json)
-                emit(envelope('sessions.help', 'ok', { usage: HELP }, null));
-            else
-                console.log(HELP);
-            return { exitCode: parsed.command ? EXIT.ok : EXIT.usage };
+            const explicitHelp = parsed.flags.has('--help') || parsed.flags.has('-h');
+            return printHelp(ctx, explicitHelp ? EXIT.ok : EXIT.usage);
         }
         try {
             const result = await executeCommand(ctx, parsed);
@@ -623,7 +647,7 @@ async function importSource(ctx, args) {
     if (provider !== 'generic' && provider !== 'claude' && provider !== 'codex'
         && provider !== 'copilot' && provider !== 'cursor' && provider !== 'factory'
         && provider !== 'hermes' && provider !== 'opencode' && provider !== 'openclaw'
-        && provider !== 'openhuman' && provider !== 'pi' && provider !== 'omp' && provider !== 'warp' && provider !== 'devin-desktop') {
+        && provider !== 'openhuman' && provider !== 'pi' && provider !== 'omp' && provider !== 'deepseek-harness' && provider !== 'warp' && provider !== 'devin-desktop') {
         throw new CliError('UNSUPPORTED_OPERATION', `session import is not implemented for ${provider}`, EXIT.unsupported);
     }
     const sourceId = requiredValue(args, '--source-id');
@@ -641,9 +665,10 @@ async function importSource(ctx, args) {
     const isOpenHuman = provider === 'openhuman';
     const isPi = provider === 'pi';
     const isOmp = provider === 'omp';
+    const isDsh = provider === 'deepseek-harness';
     const isWarp = provider === 'warp';
     const isDevinDesktop = provider === 'devin-desktop';
-    const adapter = isOmp ? new OmpSessionAdapter() : isClaude
+    const adapter = isDsh ? new DeepSeekHarnessSessionAdapter() : isOmp ? new OmpSessionAdapter() : isClaude
         ? new ClaudeSessionAdapter()
         : isCodex
             ? new CodexSessionAdapter()
@@ -668,7 +693,7 @@ async function importSource(ctx, args) {
                                                 : isDevinDesktop
                                                     ? new DevinDesktopSessionAdapter()
                                                     : new GenericSessionInterchangeAdapter();
-    const locatorClass = isOmp ? 'omp-session-v3-jsonl' : isClaude
+    const locatorClass = isDsh ? 'deepseek-harness-session-v2-jsonl' : isOmp ? 'omp-session-v3-jsonl' : isClaude
         ? (input.endsWith('.hooks.jsonl') ? 'claude-hook-jsonl' : 'claude-transcript-jsonl')
         : isCodex
             ? (input.endsWith('.app-server.jsonl') ? 'codex-app-server-jsonl' : 'codex-rollout-jsonl')
@@ -700,7 +725,7 @@ async function importSource(ctx, args) {
     const probe = await adapter.inspect(selectedSource);
     const source = SessionSourceSchema.parse({
         contractVersion: SESSION_CONTRACT_VERSION, sourceId, provider,
-        providerProfile: isOmp ? 'native-title-slot-v3' : isClaude
+        providerProfile: isDsh ? 'native-session-v2-jsonl' : isOmp ? 'native-title-slot-v3' : isClaude
             ? 'documented-local-jsonl'
             : isCodex
                 ? 'app-server-v2-rollout-fallback'
@@ -724,7 +749,7 @@ async function importSource(ctx, args) {
                                                     ? 'opt-in-cascade-transcript-hook'
                                                     : 'manual-interchange',
         locatorClass, redactedLocator: redactSourceLocator(input),
-        adapterVersion: isOmp ? OMP_ADAPTER_VERSION : isClaude
+        adapterVersion: isDsh ? DEEPSEEK_HARNESS_ADAPTER_VERSION : isOmp ? OMP_ADAPTER_VERSION : isClaude
             ? CLAUDE_ADAPTER_VERSION
             : isCodex
                 ? CODEX_ADAPTER_VERSION
@@ -751,11 +776,11 @@ async function importSource(ctx, args) {
         disposition: isWarp
             ? 'manual-only'
             : isClaude || isCodex || isCopilot || isCursor || isFactory || isHermes
-                || isOpenCode || isOpenClaw || isOpenHuman || isDevinDesktop || isOmp
+                || isOpenCode || isOpenClaw || isOpenHuman || isDevinDesktop || isOmp || isDsh || isPi
                 ? 'implemented' : 'manual-only',
         operationalState: probe.operationalState,
         consistency: probe.consistency, authorizedAt: new Date().toISOString(),
-        extensions: isOmp ? { 'native.omp': {} } : isClaude
+        extensions: isDsh ? { 'native.deepseek-harness': {} } : isOmp ? { 'native.omp': {} } : isClaude
             ? { 'native.claude': {} }
             : isCodex
                 ? { 'native.codex': {} }
@@ -821,6 +846,8 @@ async function discoverWorkspace(ctx, args) {
             : undefined,
         ompRoot: args.values.has('--omp-root')
             ? resolve(ctx.cwd, args.values.get('--omp-root')) : undefined,
+        dshRoot: args.values.has('--dsh-root')
+            ? resolve(ctx.cwd, args.values.get('--dsh-root')) : undefined,
         codexRoot: args.values.has('--codex-root')
             ? resolve(ctx.cwd, args.values.get('--codex-root'))
             : undefined,
@@ -1029,6 +1056,19 @@ function providerDisposition(provider) {
             },
         };
     }
+    if (provider === 'deepseek-harness') {
+        return {
+            provider, disposition: 'implemented', operationalState: 'available',
+            supportedOperations: ['discover', 'inspect', 'stream'], acquisitionModes: ['jsonl'],
+            reasonCode: null,
+            remediation: 'Authorize an explicit DeepSeek Harness raw JSONL sessions root. Compressed .zstd histories must be exported as raw JSONL first.',
+            evidence: {
+                adapterVersion: DEEPSEEK_HARNESS_ADAPTER_VERSION,
+                verifiedAt: '2026-09-05',
+                documentation: 'https://github.com/deepseek-ai/deepseek-harness/tree/main/packages/session/session-persistence-jsonl',
+            },
+        };
+    }
     if (provider === 'pi') {
         return {
             provider, disposition: 'implemented', operationalState: 'available',
@@ -1138,7 +1178,7 @@ function parseArgs(argv) {
         '--entity', '--sensitivity', '--extraction-state', '--page-size', '--max-documents',
         '--state', '--reviewer', '--reason', '--policy-version', '--min-confidence',
         '--consumer', '--actor-class', '--reason-code', '--dependent-action', '--basis',
-        '--manifest', '--provider-home', '--codex-root', '--omp-root', '--lock-wait-ms', '--min-coverage', '--gap',
+        '--manifest', '--provider-home', '--codex-root', '--omp-root', '--dsh-root', '--lock-wait-ms', '--min-coverage', '--gap',
         '--inactivity-threshold',
         '--control-events',
         '--session', '--status', '--actor', '--group-by',

package/dist/src/cli/handlers/steward.js

@@ -206,7 +206,7 @@ async function handleSteward(args, ctx) {
     aiwg steward permissions migrate --apply      Back up and atomically normalize config
 
   Providers:
-    antigravity (agy), claude-code, codex, copilot, cursor, factory, opencode, pi, omp, warp, windsurf, hermes, openclaw
+    antigravity (agy), claude-code, codex, copilot, cursor, deepseek-harness (dsh), factory, opencode, pi, omp, warp, windsurf, hermes, openclaw
 
   Features:
     cron, agent_teams, tasks, mcp, behaviors, mission_control, daemon

package/dist/src/cli/handlers/subcommands.js

@@ -173,6 +173,11 @@ export const catalogHandler = {
     description: "Model catalog commands (list, info, search)",
     category: "catalog",
     aliases: [],
+    async help() {
+        const { printCatalogHelp } = await import("../../catalog/cli.mjs");
+        printCatalogHelp();
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             // Dynamic import to avoid loading catalog dependencies unless needed

package/dist/src/cli/handlers/use.js

@@ -249,6 +249,36 @@ function resolveFrameworkDir(framework) {
  * aiwg-dev is contributor-only tooling — not for end users.
  */
 export const USE_ALL_DISALLOW = new Set(['aiwg-dev']);
+/** Full-framework setup requires the corpus omitted by the lightweight CLI. */
+async function bundledSetupPrerequisiteMessage(frameworkRoot) {
+    let packageName;
+    try {
+        packageName = JSON.parse(await fs.readFile(path.join(frameworkRoot, 'package.json'), 'utf8')).name;
+    }
+    catch {
+        // Embedded callers and source fixtures need not have package metadata.
+        return undefined;
+    }
+    if (packageName !== '@aiwg/cli')
+        return undefined;
+    const hasCorpus = (await Promise.all(['frameworks', 'addons'].map(async (kind) => {
+        try {
+            return (await fs.stat(path.join(frameworkRoot, 'agentic/code', kind))).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }))).every(Boolean);
+    if (hasCorpus)
+        return undefined;
+    return [
+        'Bundled framework setup requires the full aiwg package. This @aiwg/cli installation does not include framework and addon sources.',
+        'Replace the lightweight global package, then rerun your setup command:',
+        '  npm uninstall -g @aiwg/cli',
+        '  npm install -g aiwg',
+        '@aiwg/cli can still query signed web resources and deploy external project-local bundles.',
+    ].join('\n');
+}
 /**
  * Discover all addon names from the filesystem, minus the disallow list.
  */
@@ -2306,6 +2336,13 @@ export class UseHandler {
         if (framework === 'cockpit') {
             return installCockpit(ctx, remainingArgs);
         }
+        // Check before auto-init, global staging, or deployment can alter a project.
+        // Web lookup does not materialize the corpus required by bundled setup.
+        if (VALID_FRAMEWORKS.includes(framework)) {
+            const prerequisite = await bundledSetupPrerequisiteMessage(ctx.frameworkRoot || await getFrameworkRoot());
+            if (prerequisite)
+                return { exitCode: 1, message: prerequisite };
+        }
         // Structured logger for this invocation. Records go to both stderr (if
         // verbose level) and ~/.aiwg/logs/aiwg-YYYY-MM-DD.jsonl with full
         // provenance (invocation_id, aiwg_version, git_sha, etc.). #925.

package/dist/src/cli/handlers/writer-profile.js

@@ -0,0 +1,110 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { WriterProfileStore } from '../../writing/writer-profile-store.js';
+import { compileWriterProfile, exportWriterProfile, inspectWriterProfile, revokeWriterSample } from '../../writing/writer-profile.js';
+function argumentsFor(args) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        if (!['--scope', '--output', '--revision', '--mode'].includes(arg) || flags[arg] !== undefined)
+            throw new Error('Unknown or duplicate writer-profile option');
+        const value = args[++i];
+        if (!value || value.startsWith('--'))
+            throw new Error('Missing writer-profile option value');
+        flags[arg] = value;
+    }
+    const scope = flags['--scope'] ?? 'project';
+    if (scope !== 'project' && scope !== 'user')
+        throw new Error('Scope must be project or user');
+    return { positional, flags, scope };
+}
+async function execute(ctx) {
+    const { positional: [action, id, extra, ...rest], flags, scope } = argumentsFor(ctx.args);
+    if (rest.length)
+        throw new Error('Too many writer-profile arguments');
+    const store = new WriterProfileStore({ cwd: ctx.cwd, scope });
+    let result;
+    const revision = () => {
+        const raw = flags['--revision'];
+        if (raw === undefined || !/^(0|[1-9]\d*)$/.test(raw) || !Number.isSafeInteger(Number(raw)))
+            throw new Error('A nonnegative --revision is required');
+        return Number(raw);
+    };
+    const destination = () => {
+        if (!flags['--output'])
+            throw new Error('--output is required; profile content is never printed');
+        return path.resolve(ctx.cwd, flags['--output']);
+    };
+    if (ctx.dryRun)
+        return { exitCode: 1, message: 'writer-profile does not support dry-run; use inspect before changing a profile' };
+    if (action === 'list' && !id)
+        result = await store.list();
+    else if (action === 'import' && id && !extra) {
+        const input = JSON.parse(await readFile(path.resolve(ctx.cwd, id), 'utf8'));
+        result = inspectWriterProfile(await store.save(input, revision()));
+    }
+    else if (action === 'inspect' && id && !extra)
+        result = inspectWriterProfile(await store.read(id));
+    else if (action === 'version' && id && !extra) {
+        const profile = await store.read(id);
+        result = { schemaVersion: profile.schemaVersion, version: profile.version, revision: profile.revision };
+    }
+    else if (action === 'delete' && id && !extra) {
+        await store.delete(id, revision());
+        result = { deleted: true };
+    }
+    else if (action === 'revoke' && id && extra) {
+        const profile = await store.read(id);
+        result = inspectWriterProfile(await store.save(revokeWriterSample(profile, extra), revision()));
+    }
+    else if ((action === 'export' || action === 'compile') && id && !extra) {
+        const file = destination();
+        const profile = await store.read(id);
+        let output;
+        if (action === 'compile') {
+            const compiled = compileWriterProfile(profile);
+            output = compiled.profile;
+            result = { written: true, fallback: compiled.fallback, diagnostics: compiled.diagnostics, activated: false };
+        }
+        else {
+            const mode = flags['--mode'] ?? 'shared';
+            if (mode !== 'shared' && mode !== 'private')
+                throw new Error('Export mode must be shared or private');
+            output = exportWriterProfile(profile, mode);
+            result = { written: true, mode };
+        }
+        await writeFile(file, JSON.stringify(output, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    }
+    else
+        throw new Error('Invalid writer-profile command; see aiwg writer-profile --help');
+    return { exitCode: 0, rawOutput: true, message: JSON.stringify(result, null, 2) };
+}
+export const writerProfileHandler = {
+    id: 'writer-profile', name: 'Writer Profiles', description: 'Manage opt-in author-controlled writer profile sidecars', category: 'project', aliases: [],
+    async help() {
+        return { exitCode: 0, rawOutput: true, message: [
+                'aiwg writer-profile list|inspect <id>|version <id> [--scope project|user]',
+                'aiwg writer-profile import <sidecar.json> --revision 0 [--scope project|user]',
+                'aiwg writer-profile import <updated.json> --revision <current> [--scope project|user]',
+                'aiwg writer-profile export <id> --output <new-file> [--mode shared|private] [--scope project|user]',
+                'aiwg writer-profile compile <id> --output <new-file> [--scope project|user]',
+                'aiwg writer-profile revoke <id> <sample-id> --revision <current> [--scope project|user]',
+                'aiwg writer-profile delete <id> --revision <current> [--scope project|user]',
+                'Import and compile do not select an output mode. Export destinations must not exist.',
+            ].join('\n') };
+    },
+    async execute(ctx) {
+        try {
+            return await execute(ctx);
+        }
+        catch {
+            return { exitCode: 1, message: 'Writer profile operation failed. Check the command, schema, file permissions and current revision; sample content is omitted.' };
+        }
+    },
+};
+//# sourceMappingURL=writer-profile.js.map

package/dist/src/cli/handlers/writing.js

@@ -0,0 +1,122 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { parseWritingBrief, prepareWritingBrief, applyProofreadCorrections, writingBriefHash } from '../../writing/writing-brief.js';
+import { assessWritingFidelity } from '../../writing/fidelity.js';
+import { WriterProfileStore } from '../../writing/writer-profile-store.js';
+import { compileWriterProfile } from '../../writing/writer-profile.js';
+import { createWritingReceipt, writeWritingReceipt } from '../../writing/writing-receipt.js';
+import { resolveOutputModes } from '../../output-modes/registry.js';
+import { resolveProjectAiwgDirForWrite } from '../../config/project-artifacts.js';
+import { readAiwgConfig } from '../../config/aiwg-config.js';
+import { resolveArtifactOutputs, recordArtifactOutputProvenance } from '../../artifacts/output-policy.js';
+async function execute(ctx) {
+    const [action, ...args] = ctx.args;
+    if (!['plan', 'proofread'].includes(action))
+        throw new Error('Expected writing plan or proofread');
+    const flags = {};
+    const corrections = [];
+    for (let index = 0; index < args.length; index++) {
+        const key = args[index], value = args[++index];
+        if (!['--brief', '--profile', '--channel', '--output', '--correction'].includes(key) || !value || value.startsWith('--'))
+            throw new Error('Invalid writing command option');
+        if (key === '--correction')
+            corrections.push(value);
+        else {
+            if (flags[key])
+                throw new Error('Duplicate writing command option');
+            flags[key] = value;
+        }
+    }
+    if (!flags['--brief'] || !flags['--profile'])
+        throw new Error('--brief and --profile are required');
+    const channel = flags['--channel'] ?? 'engineering';
+    if (!['article', 'social', 'email', 'engineering', 'conversation'].includes(channel))
+        throw new Error('Unknown writing channel');
+    const brief = parseWritingBrief(JSON.parse(await readFile(path.resolve(ctx.cwd, flags['--brief']), 'utf8')));
+    const resolved = await resolveOutputModes(ctx.cwd, ctx.frameworkRoot, [`writer-${flags['--profile']}`]);
+    const selected = resolved.modes.find(mode => mode.id === `writer-${flags['--profile']}`);
+    if (!selected || !['project', 'user'].includes(selected.source))
+        throw new Error('A stored writer sidecar is required');
+    const profile = await new WriterProfileStore({ cwd: ctx.cwd, scope: selected.source }).read(flags['--profile']);
+    const compiled = compileWriterProfile(profile);
+    let selectedCorrections = [];
+    let output;
+    let extension;
+    let validators;
+    if (action === 'plan') {
+        if (corrections.length)
+            throw new Error('Correction selection is only valid for proofreading');
+        output = JSON.stringify(prepareWritingBrief(brief, { profileId: profile.id, channel: channel }), null, 2) + '\n';
+        extension = 'json';
+        validators = [{ id: 'writing-brief-schema', version: '1', outcome: 'pass' }];
+    }
+    else {
+        if (brief.operation !== 'proofread-only')
+            throw new Error('Proofreading requires a proofread-only brief');
+        selectedCorrections = corrections.length ? corrections : brief.permissions.corrections.map(correction => correction.id);
+        const result = applyProofreadCorrections(brief, selectedCorrections);
+        if (!result.valid)
+            throw new Error('Authorized corrections require review');
+        const original = brief.inputs.find(input => input.id === brief.sourceInputId).text;
+        const selectedBrief = { ...brief, permissions: { ...brief.permissions, corrections: brief.permissions.corrections.filter(correction => selectedCorrections.includes(correction.id)) } };
+        const fidelity = assessWritingFidelity(original, result.text, selectedBrief);
+        if (fidelity.outcome === 'fail')
+            throw new Error('Proofreading fidelity guard rejected the result');
+        output = result.text;
+        extension = 'txt';
+        validators = [{ id: 'authorized-proofread-corrections', version: '1', outcome: 'pass' }];
+        if (fidelity.outcome === 'pass')
+            validators.push({ id: 'conservative-literal-review', version: '1', outcome: 'pass' });
+    }
+    const config = await readAiwgConfig(ctx.cwd);
+    const destinations = resolveArtifactOutputs({ project: config?.artifact_outputs, supportedDestinations: ['local-file'], explicitDestinations: flags['--output'] ? ['local-file'] : [] });
+    if (flags['--output'] && !destinations.presentations.includes('local-file'))
+        throw new Error('Local presentation export is disabled by project artifact policy');
+    if (ctx.dryRun)
+        return { exitCode: 0, rawOutput: true, message: JSON.stringify({ valid: true, action, writes: false, selected: resolved.modes.map(mode => mode.id), modelExecution: 'none' }) };
+    const id = `wr-${randomUUID()}`;
+    const root = resolveProjectAiwgDirForWrite(ctx.cwd);
+    const canonical = path.join(root, 'writing', 'outputs', `${id}.${extension}`);
+    const receipt = createWritingReceipt({
+        id, operation: brief.operation,
+        profile: { id: profile.id, version: profile.version, revision: profile.revision, cacheEpoch: profile.cacheEpoch, compiledModeSha256: writingBriefHash(JSON.stringify(compiled.profile)), fallback: compiled.fallback },
+        modes: resolved.modes.map(({ source: _source, sourcePath: _sourcePath, scope: _scope, ...mode }) => ({ id: mode.id, version: mode.version, profileSha256: writingBriefHash(JSON.stringify(mode)) })),
+        state: { selected: resolved.modes.map(mode => mode.id), delivered: [], applied: [], validated: [], deliveredTo: 'none', fallback: 'none' },
+        operationConfig: { action: action, correctionIds: selectedCorrections, channel: channel },
+        modelPrompt: { execution: 'none', promptSha256: writingBriefHash(JSON.stringify(brief)) },
+        inputs: [{ id: 'brief', role: 'brief', sha256: writingBriefHash(JSON.stringify(brief)) }, ...brief.inputs.map(input => ({ id: `input-${writingBriefHash(input.id)}`, role: input.kind, sha256: input.sha256 }))],
+        output: { sha256: writingBriefHash(output), path: canonical },
+        budget: { limit: 0, used: 0, unit: 'tokens', measurement: 'exact', tokenizerId: 'no-model-call', tokenizerVersion: '1' },
+        fallback: { applied: false }, validators, authorAcceptance: { status: 'pending' },
+    });
+    await mkdir(path.dirname(canonical), { recursive: true, mode: 0o700 });
+    await writeFile(canonical, output, { flag: 'wx', mode: 0o600 });
+    const recorded = await writeWritingReceipt(ctx.cwd, receipt);
+    let presentation;
+    if (flags['--output']) {
+        presentation = path.resolve(ctx.cwd, flags['--output']);
+        await writeFile(presentation, output, { flag: 'wx', mode: 0o600 });
+        await recordArtifactOutputProvenance(root, { canonicalPath: canonical, presentationDestination: 'local-file', presentationReference: presentation, authority: 'explicit-task' });
+    }
+    return { exitCode: 0, rawOutput: true, message: JSON.stringify({ canonical, receipt: recorded.path, presentation, action, selected: resolved.modes.map(mode => mode.id), appliedModes: [], modelExecution: 'none', publicationApproval: false }) };
+}
+export const writingHandler = {
+    id: 'writing', name: 'Writing', description: 'Prepare grounded writing plans and apply authorized proofreading corrections', category: 'project', aliases: [],
+    async help() {
+        return { exitCode: 0, rawOutput: true, message: [
+                'aiwg writing plan --brief <brief.json> --profile <id> [--channel article|social|email|engineering|conversation] [--output <new-file>]',
+                'aiwg writing proofread --brief <brief.json> --profile <id> [--correction <id>]... [--output <new-file>]',
+                'Proofreading applies listed author-authorized corrections (all by default), without a model or voice rewrite.',
+                'Canonical output and a receipt are written first. Optional local exports require a new file and project-policy allowance.',
+                'Mode selections are inspected; this command does not claim provider response interception or publication approval.',
+            ].join('\n') };
+    },
+    async execute(ctx) { try {
+        return await execute(ctx);
+    }
+    catch {
+        return { exitCode: 1, message: 'Writing operation failed. Check the brief, profile, correction IDs, output destination and artifact policy. Private source text is omitted; any completed canonical artifacts remain available.' };
+    } },
+};
+//# sourceMappingURL=writing.js.map

package/dist/src/cli/router.js

@@ -77,7 +77,11 @@ export function getHookRegistry() {
 export async function run(args, options = {}) {
     const started = process.hrtime.bigint();
     const registry = await initRouter();
-    const [rawCommand, ...commandArgs] = args;
+    // Normalize `help <command>` into the same non-executing help path.
+    const routedArgs = args[0] === 'help' && args[1] && !args[1].startsWith('-')
+        ? [args[1], ...args.slice(2), '--help']
+        : args;
+    const [rawCommand, ...commandArgs] = routedArgs;
     // No command - show help
     if (!rawCommand) {
         const helpHandler = registry.handlerMap.get('help');

package/dist/src/config/project-artifacts-runtime.mjs

@@ -6,7 +6,7 @@
  */
 
 import { homedir } from 'os';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, statSync } from 'fs';
 import { isAbsolute, join, resolve } from 'path';
 
 export const DEFAULT_PROJECT_AIWG_DIR = '.aiwg';
@@ -75,10 +75,42 @@ export function resolveProjectControlDir(projectDir) {
   return resolve(projectDir, DEFAULT_PROJECT_AIWG_DIR);
 }
 
+export function isProjectArtifactRootExternal(projectDir, env = process.env) {
+  return resolve(resolveProjectAiwgDir(projectDir, env)) !== resolve(resolveProjectControlDir(projectDir));
+}
+
+/**
+ * Resolve an artifact root for a payload write. Default local mode may create
+ * `.aiwg`; an explicitly external root must already be mounted/attached so a
+ * disconnected mount cannot be silently replaced by a new local directory.
+ */
+export function resolveProjectAiwgDirForWrite(projectDir, env = process.env) {
+  const artifactRoot = resolveProjectAiwgDir(projectDir, env);
+  if (isProjectArtifactRootExternal(projectDir, env)) {
+    let available = false;
+    try {
+      available = existsSync(artifactRoot) && statSync(artifactRoot).isDirectory();
+    } catch {
+      available = false;
+    }
+    if (!available) {
+      throw new Error(
+        `Configured external AIWG artifact root is unavailable: ${artifactRoot}. ` +
+        'Reconnect or attach the external corpus; AIWG will not fall back to repository-local .aiwg payload.',
+      );
+    }
+  }
+  return artifactRoot;
+}
+
 export function projectAiwgPath(projectDir, ...segments) {
   return join(resolveProjectAiwgDir(projectDir), ...segments);
 }
 
+export function projectAiwgWritePath(projectDir, ...segments) {
+  return join(resolveProjectAiwgDirForWrite(projectDir), ...segments);
+}
+
 export function projectControlPath(projectDir, ...segments) {
   return join(resolveProjectControlDir(projectDir), ...segments);
 }

package/dist/src/config/project-artifacts.js

@@ -5,6 +5,6 @@
  * override for the project-local `.aiwg/` artifact root. Keep that contract
  * centralized so callers do not hardcode `<project>/.aiwg`.
  */
-export { AIWG_ARTIFACTS_PATH_ENV, DEFAULT_PROJECT_AIWG_DIR, PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, parseProjectArtifactLocation, projectAiwgPath, projectControlPath, readProjectArtifactLocation, resolveProjectAiwgDir, resolveProjectControlDir, } from './project-artifacts-runtime.mjs';
+export { AIWG_ARTIFACTS_PATH_ENV, DEFAULT_PROJECT_AIWG_DIR, PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, parseProjectArtifactLocation, projectAiwgPath, projectAiwgWritePath, projectControlPath, readProjectArtifactLocation, resolveProjectAiwgDir, resolveProjectAiwgDirForWrite, resolveProjectControlDir, isProjectArtifactRootExternal, } from './project-artifacts-runtime.mjs';
 export { PROJECT_CONTROL_PLANE_FILES, auditProjectArtifactHealth, } from './project-artifacts-health.mjs';
 //# sourceMappingURL=project-artifacts.js.map

package/dist/src/dataset/fortemi-dataset-execution.d.ts

@@ -0,0 +1,23 @@
+import type { McpClientLike } from "../storage/backends/fortemi.js";
+import { type FortemiDatasetRunReceipt } from "./fortemi-run-receipt.js";
+export declare const FORTEMI_DATASET_EXECUTION_TOOL = "manage_dataset_execution";
+export declare function fortemiDatasetRequestDigest(request: Record<string, unknown>): string;
+/** MCP transport binding; receipt verification is implemented independently in AIWG. */
+export declare class FortemiDatasetExecutionClient {
+    private readonly client;
+    private readonly runs;
+    constructor(client: McpClientLike);
+    private call;
+    capabilities(): Promise<Record<string, unknown>>;
+    preview(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** The caller must approve the exact digest returned by read-only preview. */
+    execute(request: Record<string, unknown>, approvedRequestDigest: string): Promise<FortemiDatasetRunReceipt>;
+    private verifyResult;
+    private knownRun;
+    retry(runId: string, action?: "retry" | "resume"): Promise<FortemiDatasetRunReceipt>;
+    status(runId: string): Promise<Record<string, unknown>>;
+    checkpoint(runId: string): Promise<Record<string, unknown>>;
+    cancel(runId: string): Promise<Record<string, unknown>>;
+    archive(runId: string): Promise<Record<string, unknown>>;
+}
+//# sourceMappingURL=fortemi-dataset-execution.d.ts.map