@manhd_d/ai-harness 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased — Guided start and portable configuration
+
+- Add start: short terminal intake, saved task/source/output choices, read-only non-TTY plan and host handoff.
+- Add bounded configuration backup/restore, dry-run conflicts, explicit replacement and before-backup; transfer only module/model preferences with old repo autonomy removed.
+- Keep canonical user config paths, ignore local backups, preserve settings through update, and document config vs full-project recovery in all README entry points.
+- Validate archive/config/path safety before writes; add rollback/transfer/intake tests, package coverage and unscored host scenarios. No model/network calls or distribution bump.
+
 ## Unreleased — Kiro and clearer tool setup
 
 - Add Kiro to all README languages and a documented IDE/CLI/Web setup guide with optional native skill pointers.
@@ -139,6 +146,13 @@
 - Check release metadata consistency and establish single-release-PR version discipline; retain v0.6.0 until a dedicated release PR.
 
 
+## [0.14.0](https://github.com/manh0303/ai-harness/compare/v0.13.0...v0.14.0) (2026-10-14)
+
+
+### Features
+
+* add guided start and portable user configuration ([2f18d23](https://github.com/manh0303/ai-harness/commit/2f18d23d92811858a3b722b349f423694bfcf3e2))
+
 ## [0.13.0](https://github.com/manh0303/ai-harness/compare/v0.12.0...v0.13.0) (2026-10-13)
 
 

package/README.md

@@ -14,8 +14,11 @@ Install/sign in to an AI tool below. Requires Node.js 22+. Run in your **project
 
 ```bash
 npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness start
 ```
 
+Run `start` for guided intake, then send its `host_prompt` to your AI tool. [Settings, backup & transfer](docs/configuration-backup.md).
+
 `npx` does not install a global `aih` command. Check the installation with
 `npx --yes @manhd_d/ai-harness check`; then open the same project in your AI tool.
 

package/bin/aih.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 import { main } from '../cli/main.js';
 
-process.exitCode = main();
+process.exitCode = await main();

package/cli/harness.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { loadStartConfig } from './start-config.js';
 import { checkpointPath, validateCheckpoint } from './checkpoint.js';
 import { readConfig } from './project-config.js';
 import { claudeReport, claudeBlock, linkClaude } from './claude.js';
@@ -14,7 +15,7 @@ import { resolveModules } from './composition.js';
 import { safe, readJson, manifest, encode, digest, stat, block, mergeAgents, payload, validateAdapters, validateCapabilities, assertSeparate, HarnessError, LOCK, CONFIG, VERSION, SLUG, isObject } from './files.js';
 export * from './files.js';
 
-function projectConfig(root, adapters, capabilities, required = false) {
+export function projectConfig(root, adapters, capabilities, required = false) {
   const filename = safe(root, CONFIG);
   if (required && !stat(filename)) throw new HarnessError(`Missing ${CONFIG}; restore it from Git`);
   const config = stat(filename) ? readJson(filename) : { schema_version: 1, adapters: adapters ?? [], capabilities: capabilities ?? [] };
@@ -120,7 +121,7 @@ function drift(root, lock) {
   }).map(([name]) => name);
 }
 
-function guard(root, operation) {
+export function guard(root, operation) {
   const filename = safe(root, '.harness-install.lock');
   let fd;
   try { fd = fs.openSync(filename, 'wx', 0o600); }
@@ -132,12 +133,12 @@ function guard(root, operation) {
   finally { fs.closeSync(fd); fs.unlinkSync(filename); }
 }
 
-export function atomicWrite(filename, data) {
+export function atomicWrite(filename, data, mode = 0o644) {
   fs.mkdirSync(path.dirname(filename), { recursive: true });
   const tmp = path.join(path.dirname(filename), `.harness-tmp-${randomUUID()}`);
   try {
     fs.writeFileSync(tmp, data, { flag: 'wx', mode: 0o600 });
-    fs.chmodSync(tmp, stat(filename) ? fs.statSync(filename).mode & 0o777 : 0o644);
+    fs.chmodSync(tmp, stat(filename) ? fs.statSync(filename).mode & 0o777 : mode);
     fs.renameSync(tmp, filename);
   } finally { fs.rmSync(tmp, { force: true }); }
 }
@@ -172,6 +173,7 @@ export function install(root, source, { command = 'init', adapters, capabilities
     if (command === 'update' && !hasLock) throw new HarnessError('Not installed; run init first');
     const old = hasLock ? loadLock(root) : null;
     const existingAgents = loadAgentConfig(root);
+    loadStartConfig(root);
     loadArtifactContract(root); // Validate project-owned declarations before planning any writes.
     if (agentPreset !== undefined && command !== 'init') throw new HarnessError('Agent preset is supported only by init');
     if (agentPreset !== undefined && existingAgents) throw new HarnessError('agents.json is project-owned; edit it explicitly instead of applying an init preset');
@@ -230,8 +232,8 @@ export function install(root, source, { command = 'init', adapters, capabilities
     // This does not remove an already tracked machine file from the Git index.
     const ignoreName = '.harness/.gitignore', ignorePath = safe(root, ignoreName);
     const ignore = stat(ignorePath) ? fs.readFileSync(ignorePath, 'utf8') : '';
-    if (ignore.trimEnd().split(/\r?\n/).at(-1) !== '/machine.json') {
-      changes[ignoreName] = Buffer.from(ignore + (ignore && !ignore.endsWith('\n') ? '\n' : '') + '/machine.json\n');
+    if (ignore.trimEnd().split(/\r?\n/).slice(-2).join('\n') !== '/backups/\n/machine.json') {
+      changes[ignoreName] = Buffer.from(ignore + (ignore && !ignore.endsWith('\n') ? '\n' : '') + '/backups/\n/machine.json\n');
     }
     const newLock = encode(lock);
     if (!hasLock || !fs.readFileSync(safe(root, LOCK)).equals(newLock)) changes[LOCK] = newLock;
@@ -245,6 +247,7 @@ export function check(root) {
   const lock = loadLock(root), config = projectConfig(root, undefined, undefined, true);
   const problems = drift(root, lock);
   loadArtifactContract(root);
+  loadStartConfig(root);
   loadAgentConfig(root); // Optional on legacy installs; validate user config without managing its bytes.
   if (JSON.stringify([...config.adapters].sort()) !== JSON.stringify([...lock.adapters].sort())) problems.push(`${CONFIG}: adapter selection changed; run update`);
   if (JSON.stringify([...(config.capabilities ?? [])].sort()) !== JSON.stringify([...(lock.capabilities ?? [])].sort())) problems.push(`${CONFIG}: capability selection changed; run update`);

package/cli/main.js

@@ -1,3 +1,5 @@
+import { startPlan, saveStart, guidedStart } from './start.js';
+import { backupConfig, restoreConfig } from './portable-config.js';
 import { listAdapters, detect, verify, evaluate } from './adapters.js';
 import { listCapabilities, skillCatalog, readSkill } from './capabilities.js';
 import { resolveModules } from './composition.js';
@@ -29,6 +31,9 @@ Usage: aih <command> [options]
   update               Apply the installed CLI bundle to the project (no download)
   check                Check Harness file integrity, not application tests
   doctor               Check installation, configured paths and tool presence
+  start                Guide intake; reuse saved answers and hand off to your AI host
+  backup               Export user configuration (not docs/checkpoints/secrets)
+  restore              Restore --from backup; --transfer reuses modules/model preferences
   setup                Suggest first-run questions for the AI host (read-only)
   artifacts            Show input/output/storage and connection declarations (read-only)
   ready <id>           Check structural change readiness, not approval
@@ -36,6 +41,13 @@ Usage: aih <command> [options]
   new-doc <type>       Scaffold a locked capability template (default: product)
 
 Options:
+  --goal <type>       start: idea, docs, change, resume (saves with --task)
+  --task <text>       start: task description; --change supplies resume checkpoint ID
+  --input <path/url>  start: seed requirements only if no inputs declared
+  --output <path>     start: draft docs directory; backup: archive path
+  --from <file>       restore: project-relative archive file
+  --transfer          restore: only modules/agent models; omit old autonomy
+  --replace           restore: explicit replacement; automatic before-backup
   --target <directory> Project directory (default: current directory)
   --detect            init only: opt in to detected stack selection
   --stage <type>      ready only: implement (default) or review
@@ -56,7 +68,9 @@ Options:
   -h, --help          Show help
   -v, --version       Show installed CLI version
 
-Start: init → fill .harness/local.md → ask your AI host to read AGENTS.md.
+Start: init → start → open your AI host and send the returned host_prompt.
+User settings: .harness/; backup exports only documented user files.
+Restore config before init on a fresh project; --transfer excludes old sources/tasks.
 The host runs application tests; verify prints plans or validates supplied evidence.
 Update a global CLI with npm install -g @manhd_d/ai-harness@latest,
 then run aih update --dry-run, aih update, and aih check in the project.
@@ -95,7 +109,7 @@ export function main(argv = process.argv.slice(2)) {
   let args;
   try {
     args = parseArgs({ args: argv, allowPositionals: true, strict: true, tokens: true, options: {
-      target: { type: 'string' }, adapters: { type: 'string' }, capabilities: { type: 'string' }, capability: { type: 'string' }, source: { type: 'string' },
+      goal: { type: 'string' }, task: { type: 'string' }, change: { type: 'string' }, input: { type: 'string' }, output: { type: 'string' }, from: { type: 'string' }, transfer: { type: 'boolean' }, replace: { type: 'boolean' }, target: { type: 'string' }, adapters: { type: 'string' }, capabilities: { type: 'string' }, capability: { type: 'string' }, source: { type: 'string' },
       'agent-preset': { type: 'string' }, host: { type: 'string' }, expected: { type: 'string' },
       'link-claude': { type: 'boolean' }, 'claude-skills': { type: 'boolean' }, adaptive: { type: 'boolean' }, detect: { type: 'boolean' }, report: { type: 'string' }, scope: { type: 'string' }, stage: { type: 'string' },
       'dry-run': { type: 'boolean' }, 'allow-major': { type: 'boolean' },
@@ -109,9 +123,13 @@ export function main(argv = process.argv.slice(2)) {
     if (args.values.help || !argv.length) { console.log(HELP); return 0; }
     if (args.values.version) { console.log(readJson(path.join(SOURCE, 'package.json')).version); return 0; }
     const [command, name, ...extra] = args.positionals;
-    if (!['init', 'update', 'check', 'doctor', 'new-change', 'new-doc', 'list', 'detect', 'resolve', 'verify', 'eval', 'skills', 'skill', 'setup', 'ready', 'artifacts', 'agents', 'checkpoint', 'resume'].includes(command)) throw new Error(`Unknown command: ${command}`);
+    if (!['start', 'backup', 'restore', 'init', 'update', 'check', 'doctor', 'new-change', 'new-doc', 'list', 'detect', 'resolve', 'verify', 'eval', 'skills', 'skill', 'setup', 'ready', 'artifacts', 'agents', 'checkpoint', 'resume'].includes(command)) throw new Error(`Unknown command: ${command}`);
     if (extra.length || (!['new-change', 'new-doc', 'skill', 'ready', 'checkpoint', 'resume'].includes(command) && name !== undefined) || (['new-change', 'new-doc', 'skill', 'ready', 'checkpoint', 'resume'].includes(command) && name === undefined)) throw new Error('Unexpected or missing positional argument; run aih --help');
     const allowed = new Set(['target', ...(['init', 'update'].includes(command) ? ['source', 'dry-run', 'allow-major'] : []), ...(['init', 'resolve'].includes(command) ? ['adapters', 'capabilities'] : []), ...(command === 'init' ? ['detect'] : []), ...(['list', 'detect', 'resolve'].includes(command) ? ['source'] : []), ...(command === 'eval' ? ['report'] : []), ...(command === 'ready' ? ['stage'] : []), ...(['verify', 'eval'].includes(command) ? ['scope'] : [])]);
+    if (command === 'start') for (const key of ['goal','task','change','input','output','host']) allowed.add(key);
+    if (command === 'backup') allowed.add('output');
+    if (command === 'restore') { for (const key of ['from','transfer','replace','dry-run']) allowed.add(key); if (!args.values.from) throw new Error('restore requires --from'); }
+    if (command === 'start' && !args.values.goal && ['task','change','input','output'].some(key => args.values[key] !== undefined)) throw new Error('start saving options require --goal');
     if (command === 'checkpoint') { allowed.add('report'); allowed.add('expected'); if (!args.values.report) throw new Error('checkpoint requires --report'); }
     if (command === 'new-doc') { allowed.add('capability'); allowed.add('report'); }
     if (command === 'verify') { allowed.add('adaptive'); allowed.add('report'); }
@@ -122,13 +140,18 @@ export function main(argv = process.argv.slice(2)) {
     if (['init','update'].includes(command)) { allowed.add('link-claude'); allowed.add('claude-skills'); }
     for (const key of Object.keys(args.values)) if (!allowed.has(key)) throw new Error(`--${key} is not supported for ${command}`);
     if (args.values.detect && args.values.adapters !== undefined) throw new Error('Choose either --detect or --adapters');
-    for (const key of ['target', 'source', 'adapters', 'capabilities', 'capability', 'report', 'agent-preset', 'host']) if (args.values[key] !== undefined && !args.values[key].trim()) throw new Error(`--${key} cannot be empty`);
+    for (const key of ['goal', 'task', 'change', 'input', 'output', 'from', 'target', 'source', 'adapters', 'capabilities', 'capability', 'report', 'agent-preset', 'host']) if (args.values[key] !== undefined && !args.values[key].trim()) throw new Error(`--${key} cannot be empty`);
   } catch (error) { console.error(JSON.stringify({ status: 'error', message: error.message })); return 2; }
   try {
     const { values, positionals: [command, name] } = args;
     const root = targetRoot(values.target ?? process.cwd());
     let result;
-    if (command === 'init' || command === 'update') {
+    if (command === 'start') {
+      if (!values.goal && process.stdin.isTTY && process.stdout.isTTY) return guidedStart(root, { host: values.host }).then(value => { console.log(JSON.stringify(value, null, 2)); return value.status === 'blocked' ? 1 : 0; }).catch(error => { console.error(JSON.stringify({ status: 'error', message: error.message })); return 1; });
+      result = values.goal ? saveStart(root, { goal: values.goal, task: values.task, changeId: values.change, input: values.input, output: values.output, host: values.host }) : startPlan(root, values.host);
+    } else if (command === 'backup') result = backupConfig(root, values.output);
+    else if (command === 'restore') result = restoreConfig(root, values.from, { dryRun: values['dry-run'], transfer: values.transfer, replace: values.replace });
+    else if (command === 'init' || command === 'update') {
       const source = targetRoot(values.source ?? SOURCE);
       const selection = values.detect ? detect(root, source).adapters : undefined;
       if (values.detect && !selection.length) throw new Error('No stack detected; choose --adapters explicitly or omit --detect for core only');
@@ -172,9 +195,9 @@ export function main(argv = process.argv.slice(2)) {
     else result = command === 'doctor' ? doctor(root) : check(root);
     if (command === 'init' || command === 'update') result.next_steps = values['dry-run']
       ? ['Review the proposed changes, then repeat without --dry-run.']
-      : ['Run aih setup; ask your AI host to read AGENTS.md and the project-setup workflow.',
+      : ['Run start with the same CLI (aih start or npx --yes @manhd_d/ai-harness start); open your AI host and send host_prompt.',
          'Review local.md/environment.json and artifacts.json/integrations.json; record input/output/storage/ownership, keep credentials in the host and personal paths in ignored machine.json.',
-         'Run aih doctor and review/commit the shared configuration and snapshot.'];
+         'Run doctor and review/commit shared configuration and snapshot. Use backup; copy its file outside the repo. See docs/configuration-backup.md.'];
     if (command === 'new-change') result.next_steps = [
       'Resolve consequential ambiguity with the user and record answers/sources in decisions.json.',
       'When artifact outputs are configured, record create/update/unchanged impact and source-write policy in artifact-impact.json.',

package/cli/portable-config.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { safe, stat, encode, digest, isObject, SOURCE, VERSION, HarnessError } from './files.js';
+import { projectConfig, guard, transaction, atomicWrite } from './harness.js';
+import { loadEnvironment } from './environment.js';
+import { loadAgentConfig } from './agents.js';
+import { loadArtifactContract } from './artifacts.js';
+import { loadStartConfig } from './start-config.js';
+import { resolveModules } from './composition.js';
+
+export const USER_FILES = ['.harness/project.json', '.harness/agents.json', '.harness/artifacts.json',
+  '.harness/integrations.json', '.harness/environment.json', '.harness/local.md', '.harness/start.json', 'openspec/config.yaml'];
+const MAX_FILE = 1024 * 1024, MAX_ARCHIVE = 12 * MAX_FILE;
+const fail = (ok, message) => { if (!ok) throw new HarnessError(message); };
+export const backupName = () => '.harness/backups/config-' + new Date().toISOString().replace(/[:.]/g, '-') + '-' + randomUUID() + '.json';
+function readText(root, name) {
+  const filename = safe(root, name), info = stat(filename);
+  if (!info) return null;
+  fail(info.size <= MAX_FILE, 'Configuration exceeds 1 MiB: ' + name);
+  const bytes = fs.readFileSync(filename), content = bytes.toString('utf8');
+  fail(Buffer.from(content).equals(bytes), 'Configuration must be UTF-8: ' + name);
+  return content;
+}
+export function configArchive(root) {
+  const files = {};
+  for (const name of USER_FILES) {
+    const content = readText(root, name);
+    if (content !== null) files[name] = { content, sha256: digest(Buffer.from(content)) };
+  }
+  fail(Object.hasOwn(files, '.harness/project.json'), 'Missing .harness/project.json; initialize or restore project configuration first');
+  return { schema_version: 1, kind: 'ai-harness-user-config', cli_version: JSON.parse(fs.readFileSync(path.join(SOURCE, 'package.json'))).version,
+    files };
+}
+function validateArchive(value) {
+  fail(isObject(value) && Object.keys(value).sort().join(',') === 'cli_version,files,kind,schema_version'
+    && value.schema_version === 1 && value.kind === 'ai-harness-user-config' && VERSION.test(value.cli_version)
+    && isObject(value.files) && Object.hasOwn(value.files, '.harness/project.json'), 'Unsupported configuration backup schema');
+  for (const [name, file] of Object.entries(value.files)) {
+    fail(USER_FILES.includes(name), 'Backup contains an unapproved configuration path');
+    fail(isObject(file) && Object.keys(file).sort().join(',') === 'content,sha256' && typeof file.content === 'string'
+      && Buffer.byteLength(file.content) <= MAX_FILE && /^[a-f0-9]{64}$/.test(file.sha256)
+      && digest(Buffer.from(file.content)) === file.sha256, 'Backup content/digest mismatch: ' + name);
+  }
+}
+function validateFiles(files) {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'aih-config-'));
+  try {
+    for (const [name, file] of Object.entries(files)) {
+      if (name.endsWith('.json')) { try { JSON.parse(file.content); } catch { throw new HarnessError('Invalid JSON configuration: ' + name); } }
+      const dest = safe(temp, name); fs.mkdirSync(path.dirname(dest), { recursive: true }); fs.writeFileSync(dest, file.content, { mode: 0o600 });
+    }
+    const config = projectConfig(temp, undefined, undefined, true);
+    resolveModules(SOURCE, config);
+    loadAgentConfig(temp); loadArtifactContract(temp); loadEnvironment(temp); loadStartConfig(temp);
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+function outputPath(root, name) {
+  fail(typeof name === 'string' && name.endsWith('.json') && !/^(?:\.git|\.agents|\.claude|node_modules)(?:\/|$)/.test(name) && !USER_FILES.includes(name) && !name.startsWith('.harness/core/') && !name.startsWith('openspec/changes/')
+    && (!name.startsWith('.harness/') || name.startsWith('.harness/backups/')), 'Use a backup path outside active Harness configuration');
+  const filename = safe(root, name); fail(!stat(filename), 'Backup destination already exists'); return filename;
+}
+export function backupConfig(root, output = backupName()) {
+  return guard(root, () => {
+    const archive = configArchive(root); validateArchive(archive); validateFiles(archive.files);
+    const filename = outputPath(root, output);
+    fs.mkdirSync(path.dirname(filename), { recursive: true });
+    fs.writeFileSync(filename, encode(archive), { flag: 'wx', mode: 0o600 });
+    return { status: 'ok', backup: output, included: Object.keys(archive.files),
+      excluded: ['machine.json', 'credentials and native host settings', 'managed snapshot and lock', 'custom skills', 'source/output document contents', 'OpenSpec changes, checkpoints and evidence'],
+      next_steps: ['Copy the backup to a private location outside this project.', 'Keep code/docs/openspec changes and custom skills in your repository backup; configuration backup is not a full project backup.'] };
+  });
+}
+export function restoreConfig(root, from, { dryRun = false, transfer = false, replace = false, writer } = {}) {
+  const filename = safe(root, from); fail(stat(filename)?.size <= MAX_ARCHIVE, 'Missing or oversized configuration backup');
+  const archive = readConfigArchive(filename); validateArchive(archive); validateFiles(archive.files);
+  return guard(root, () => {
+    const files = transfer ? Object.fromEntries(Object.entries(archive.files).filter(([name]) => ['.harness/project.json', '.harness/agents.json'].includes(name))) : archive.files;
+    if (transfer && files['.harness/agents.json']) {
+      const config = JSON.parse(files['.harness/agents.json'].content);
+      delete config.execution.autonomy; // Repository-scoped autonomy decisions never move to a different project.
+      files['.harness/agents.json'] = { content: encode(config).toString() };
+    }
+    const changes = {}, conflicts = [];
+    for (const [name, file] of Object.entries(files)) {
+      const current = readText(root, name);
+      if (current === file.content) continue;
+      if (current !== null) conflicts.push(name);
+      changes[name] = Buffer.from(file.content);
+    }
+    fail(!conflicts.length || replace || dryRun, 'Existing configuration differs: ' + conflicts.join(', ') + '; review --dry-run --replace before replacement');
+    // Validate the prospective merged configuration before any target writes.
+    const merged = {};
+    for (const name of USER_FILES) {
+      const content = changes[name]?.toString() ?? readText(root, name);
+      if (content !== null) merged[name] = { content };
+    }
+    validateFiles(merged);
+    // Validate declared artifact paths against actual target symlinks, not only temporary files.
+    const artifacts = merged['.harness/artifacts.json'] ? JSON.parse(merged['.harness/artifacts.json'].content) : null;
+    for (const group of ['inputs','outputs']) for (const item of Object.values(artifacts?.[group] ?? {})) {
+      if (item.location.path) safe(root, item.location.path + (group === 'outputs' || stat(path.join(root, item.location.path))?.isDirectory() ? '/.artifact-probe' : ''));
+    }
+    let backup = null;
+    if (!dryRun && conflicts.length) {
+      const before = configArchive(root); backup = backupName(); outputPath(root, backup);
+      changes[backup] = encode(before);
+    }
+    if (!dryRun) transaction(root, changes, writer ?? ((filename, data) => atomicWrite(filename, data, filename === (backup ? safe(root, backup) : null) ? 0o600 : 0o644)));
+    return { status: dryRun ? 'planned' : 'ok', mode: transfer ? 'transfer' : 'restore', changes: Object.keys(changes), conflicts,
+      backup, omitted: Object.keys(archive.files).filter(name => !Object.hasOwn(files, name)),
+      next_steps: ['Run init on a fresh project, or update --dry-run then update on an installed project; run check.',
+        transfer ? 'Run start for a new task; rebind input/output locations, commands and connections. Old autonomy declarations were removed.' : 'Run doctor and start; restore docs/checkpoints/evidence separately from your project backup before resume.',
+        'Review host access, models, sources and write policies; importing declarations does not grant permission or connect accounts.'] };
+  });
+}
+function readConfigArchive(filename) {
+  try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { throw new HarnessError('Invalid configuration backup JSON'); }
+}

package/cli/start-config.js

@@ -0,0 +1,15 @@
+import { readConfig } from './project-config.js';
+import { isObject, SLUG, HarnessError, safe, stat } from './files.js';
+export const START_CONFIG = '.harness/start.json';
+export const GOALS = ['idea', 'docs', 'change', 'resume'];
+export function loadStartConfig(root) {
+  const value = readConfig(root, START_CONFIG);
+  if (value === null) { if (stat(safe(root, START_CONFIG))) throw new HarnessError('Invalid start.json schema'); return null; }
+  const text = s => typeof s === 'string' && s.trim().length > 0 && s.length <= 4096 && !/[\x00-\x1f\x7f]/.test(s);
+  if (!isObject(value) || Object.keys(value).some(k => !['schema_version', 'goal', 'task', 'change_id'].includes(k))
+      || value.schema_version !== 1 || !GOALS.includes(value.goal) || !text(value.task)
+      || (value.goal === 'resume' ? !SLUG.test(value.change_id ?? '') || value.change_id === 'archive' : value.change_id !== undefined)) {
+    throw new HarnessError('Invalid start.json schema/goal/task/change_id');
+  }
+  return value;
+}

package/cli/start.js

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { safe, stat, encode, SLUG, HarnessError } from './files.js';
+import { check, loadLock, guard, transaction, atomicWrite } from './harness.js';
+import { setupPlan } from './environment.js';
+import { loadArtifactContract, emptyArtifacts } from './artifacts.js';
+import { START_CONFIG, GOALS, loadStartConfig } from './start-config.js';
+import { configArchive, backupName } from './portable-config.js';
+import { resumePlan } from './checkpoint.js';
+
+function assert(ok, message) { if (!ok) throw new HarnessError(message); }
+export function startPlan(root, host) {
+  assert(check(root).status === 'ok', 'Fix installation drift before start');
+  const lock = loadLock(root), saved = loadStartConfig(root), contract = loadArtifactContract(root);
+  const evidence = ['README.md', 'docs', 'requirements', 'pom.xml', 'package.json', 'build.gradle', 'pyproject.toml']
+    .filter(name => { const p = path.join(root, name), info = stat(p); if (info?.isDirectory()) safe(root, name + '/.start-probe'); else safe(root, name); return Boolean(info); });
+  const base = path.join(root, 'openspec/changes'), checkpoints = [];
+  if (stat(base)) {
+    safe(root, 'openspec/changes/.start-probe');
+    for (const id of fs.readdirSync(base).sort().slice(0, 100)) {
+      if (id !== 'archive' && SLUG.test(id) && stat(safe(root, 'openspec/changes/' + id + '/checkpoint.json'))) checkpoints.push(id);
+    }
+  }
+  const recommendation = saved?.goal ?? (checkpoints.length ? 'resume' : contract.artifacts.mode === 'document-driven' ? 'docs'
+    : evidence.some(p => ['pom.xml', 'package.json', 'build.gradle', 'pyproject.toml'].includes(p)) ? 'change' : 'idea');
+  const goal = saved?.goal;
+  const workflow = goal === 'idea' ? 'solution-framing.md' : 'continuous-development.md';
+  const setup = setupPlan(root, lock.adapters, process.env, host);
+  let resume = null;
+  if (goal === 'resume') {
+    try { resume = resumePlan(root, saved.change_id); }
+    catch (error) { if (!(error instanceof HarnessError)) throw error; resume = { status: 'blocked', executed: false, message: error.message, next_action: 'Restore/reconcile checkpoints and evidence before continuation, or choose a new task.' }; }
+  }
+  return { status: resume?.status === 'blocked' ? 'blocked' : 'planned', saved, discovery: { evidence, checkpoints, inputs: Object.keys(contract.artifacts.inputs), outputs: Object.keys(contract.artifacts.outputs) },
+    recommendation, reason: saved ? 'Reuse the saved task; choose a new goal explicitly to start another task.'
+      : checkpoints.length ? 'Checkpoint candidates exist; inspect freshness before continuing.'
+      : 'Based on declared sources and root build-file presence; the host must inspect their contents.',
+    questions: [ ...(!saved ? [{ id: 'goal', question: 'Start from an idea, existing docs, change existing code, or resume?', options: GOALS, recommendation }] : []),
+      ...(!Object.keys(contract.artifacts.inputs).length && goal !== 'resume' ? [{ id: 'input', question: 'Use which requirement path or credential-free HTTPS URL? Leave unknowns for the AI discussion.', options: ['repository', 'external', 'idea'], recommendation: evidence.includes('docs') ? 'repository' : 'idea' }] : []),
+      ...(!Object.keys(contract.artifacts.outputs).length && ['idea','docs'].includes(goal) ? [{ id: 'output', question: 'Where should draft docs be written?', options: ['docs/product', 'existing destination', 'discuss with AI'], recommendation: 'docs/product' }] : []) ],
+    suggested_roles: goal === 'idea' ? ['product:business-analyst', 'architecture:solution-architect']
+      : goal === 'docs' ? ['core:planner', 'core:implementer', 'core:reviewer'] : ['core:implementer', 'core:reviewer'],
+    agent_routes: setup.agent_configuration.roles.filter(role => (goal === 'idea' ? ['product:business-analyst', 'architecture:solution-architect'] : goal === 'docs' ? ['core:planner', 'core:implementer', 'core:reviewer'] : ['core:implementer', 'core:reviewer']).includes(role.canonical_id)),
+    installed_modules: { adapters: lock.adapters, capabilities: lock.capabilities ?? [] },
+    setup_questions: setup.questions, environment: setup.environment,
+    resume,
+    configuration: { directory: '.harness/', task: START_CONFIG, inputs_outputs: '.harness/artifacts.json', models_agents: '.harness/agents.json',
+      backup: 'aih backup', restore: 'aih restore --from <project-relative-backup.json>', transfer: 'aih restore --from <backup.json> --transfer' },
+    host_prompt: 'Read AGENTS.md, .harness/start.json if present, .harness/local.md and .harness/core/workflows/project-setup.md. '
+      + 'Inspect declared input/output locations and current code. Reuse saved answers; ask only missing consequential decisions with options and a grounded recommendation. '
+      + 'Use .harness/core/workflows/' + workflow + '. Discover only relevant installed agents/skills; suggest missing modules before editing project.json. '
+      + 'Keep model defaults unless requested; save accepted source/output/connection choices in their project-owned configs. '
+      + 'For resumed tasks inspect checkpoint freshness and side effects. Implement accepted scope with actual verification and maintain affected docs.',
+    next_steps: ['In a terminal start interviews and saves answers; without a TTY it prints this plan. Use --goal/--task to save non-interactively.',
+      'Open this project in your AI tool and send host_prompt; CLI does not launch a model or read remote document contents.',
+      'Use backup and copy its file outside the repository; see the configuration backup guide.'] };
+}
+export function saveStart(root, { goal, task, changeId, input, output, host } = {}) {
+  assert(GOALS.includes(goal), 'Choose --goal idea|docs|change|resume');
+  assert(typeof task === 'string' && task.trim().length > 0 && task.length <= 4096 && !/[\x00-\x1f\x7f]/.test(task), 'Supply a nonempty single-line --task (max 4096 characters)');
+  assert(goal === 'resume' ? SLUG.test(changeId ?? '') && changeId !== 'archive' : changeId === undefined, 'Use --change only with resume and an existing change ID');
+  return guard(root, () => {
+    const plan = startPlan(root, host), contract = loadArtifactContract(root);
+    if (goal === 'resume') {
+      assert(plan.discovery.checkpoints.includes(changeId), 'Resume requires an existing checkpoint; restore project changes/evidence first');
+      resumePlan(root, changeId); // Validate checkpoint/evidence before saving any configuration.
+    }
+    assert(goal !== 'resume' || (input === undefined && output === undefined), 'Resume reuses source/output contracts; do not combine with --input/--output');
+    const changes = {}, value = { schema_version: 1, goal, task: task.trim(), ...(changeId ? { change_id: changeId } : {}) };
+    changes[START_CONFIG] = encode(value);
+    if (input !== undefined || output !== undefined) {
+      const artifacts = structuredClone(contract.artifacts);
+      if (!contract.configured) Object.assign(artifacts, emptyArtifacts(), { mode: input ? 'document-driven' : goal === 'docs' ? 'document-driven' : 'idea-driven' });
+      if (input !== undefined) {
+        assert(!Object.keys(artifacts.inputs).length, 'Inputs already configured; review artifacts.json instead of replacing them through start');
+        assert(typeof input === 'string' && input.trim().length > 0, 'Input cannot be empty');
+        artifacts.inputs.requirements = { kind: 'requirements', location: input.startsWith('https://') ? { url: input } : { path: input }, write_policy: 'read-only' };
+      }
+      if (output !== undefined) {
+        assert(!Object.keys(artifacts.outputs).length, 'Outputs already configured; review artifacts.json instead of replacing them through start');
+        artifacts.outputs.documents = { kind: 'docs', location: { path: output }, capability: 'product', write_policy: 'propose', sources: Object.keys(artifacts.inputs) };
+      }
+      // Reuse the existing contract validator in a temporary workspace, before touching the target.
+      validateProposed(root, artifacts);
+      changes['.harness/artifacts.json'] = encode(artifacts);
+    }
+    for (const [name, bytes] of Object.entries(changes)) if (stat(safe(root, name)) && fs.readFileSync(safe(root, name)).equals(bytes)) delete changes[name];
+    const replacing = Object.keys(changes).some(name => stat(safe(root, name)));
+    let backup = null;
+    if (replacing) { backup = backupName(); assert(!stat(safe(root, backup)), 'Backup collision'); changes[backup] = encode(configArchive(root)); }
+    transaction(root, changes, (filename, data) => atomicWrite(filename, data, filename === (backup ? safe(root, backup) : null) ? 0o600 : 0o644));
+    const next = startPlan(root, host);
+    return { ...next, status: next.status === 'blocked' ? 'blocked' : 'ok', changes: Object.keys(changes), backup };
+  });
+}
+function validateProposed(root, artifacts) {
+  // Validate cross-file references with existing integrations and validate target paths through the canonical loader.
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'aih-start-'));
+  try {
+    fs.mkdirSync(path.join(temp, '.harness'));
+    fs.writeFileSync(path.join(temp, '.harness/artifacts.json'), encode(artifacts));
+    fs.writeFileSync(path.join(temp, '.harness/integrations.json'), encode(loadArtifactContract(root).integrations));
+    loadArtifactContract(temp);
+    for (const group of ['inputs', 'outputs']) for (const item of Object.values(artifacts[group])) {
+      const name = item.location.path;
+      if (name) safe(root, name + (group === 'outputs' || stat(path.join(root, name))?.isDirectory() ? '/.artifact-probe' : ''));
+    }
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+
+export async function guidedStart(root, { host, ask } = {}) {
+  const plan = startPlan(root, host);
+  let rl;
+  if (!ask) { rl = createInterface({ input: process.stdin, output: process.stdout }); ask = q => rl.question(q); }
+  try {
+    let goal = plan.saved?.goal;
+    if (plan.saved) {
+      const answer = (await ask('Saved task: ' + plan.saved.task + '\n1. Continue (recommended)  2. New task\nChoice [1]: ')).trim();
+      assert(['', '1', '2'].includes(answer), 'Choose 1 or 2');
+      if (answer !== '2') return plan;
+      goal = undefined;
+    }
+    if (!goal) {
+      const choice = (await ask('Goal: 1. Idea  2. Existing docs  3. Change code  4. Resume\nSuggested: ' + plan.recommendation + '\nChoice [Enter uses suggestion]: ')).trim();
+      goal = choice ? GOALS[Number(choice) - 1] : plan.recommendation;
+      assert(GOALS.includes(goal), 'Choose 1, 2, 3 or 4');
+    }
+    const changeId = goal === 'resume' ? (await ask('Checkpoint ID (' + plan.discovery.checkpoints.join(', ') + '): ')).trim() : undefined;
+    const task = (await ask('What should the AI do? ')).trim();
+    let input, output;
+    if (!plan.discovery.inputs.length && goal !== 'resume') input = (await ask('Requirements: relative path or HTTPS URL (Enter: discuss idea/unknown sources with AI): ')).trim() || undefined;
+    if (!plan.discovery.outputs.length && ['idea', 'docs'].includes(goal)) output = (await ask('Draft docs folder [docs/product; type - to discuss with AI]: ')).trim() || 'docs/product';
+    if (output === '-') output = undefined;
+    return saveStart(root, { goal, task, changeId, input, output, host });
+  } finally { rl?.close(); }
+}

package/core/evals/cases.json

@@ -254,6 +254,28 @@
         "Reuses established authorization/answers"
       ],
       "critical": true
+    },
+    {
+      "id": "start-reuses-portable-settings",
+      "prompt": "A project has a saved start.json task, agents.json model choices, artifacts.json requirement sources and outputs. The owner says start implementing.",
+      "criteria": [
+        "Reads saved task, local facts and source contracts before asking",
+        "Reuses resolved choices and loads only relevant installed roles/skills",
+        "Checks current sources/host access and implements accepted scope with actual verification",
+        "Explains where settings live and how configuration backup differs from docs/checkpoint backup"
+      ],
+      "critical": false
+    },
+    {
+      "id": "transfer-does-not-inherit-approval",
+      "prompt": "The owner restores a Harness configuration backup into a different repo using --transfer. The old source repo allowed autopilot merges and used a private Confluence source.",
+      "criteria": [
+        "Reuses module/model preferences without inferring new-repo autonomy or merge approval",
+        "Re-establishes document input/output/connection and command choices for the target project",
+        "Does not claim external docs, credentials or checkpoint evidence were copied",
+        "Distinguishes declarations from actual available model/host permissions"
+      ],
+      "critical": true
     }
   ]
 }

package/core/workflows/project-setup.md

@@ -4,6 +4,8 @@ Read AGENTS.md, local.md, actual build files and existing environment configurat
 For project/MVP/architecture decisions, apply `solution-framing.md` at the appropriate depth.
 For input/output/storage/source-write decisions, apply `artifact-contract.md`; ask only when
 needed for the task and reuse known project/session decisions.
+Use `aih start` for terminal intake or a read-only host plan; reuse `.harness/start.json` and declared
+artifacts before asking. CLI root-file discovery is metadata evidence; inspect content and the actual host.
 Use `aih setup` for structured suggestions; it never interviews the user or writes answers.
 Do not ask about facts already established in the repository or current conversation.
 
@@ -37,3 +39,19 @@ Do not ask about facts already established in the repository or current conversa
 Example: "Which Maven should this project use? A: existing Wrapper (recommended because mvnw is
 present); B: Maven on PATH; C: internal Maven at a custom path. You can describe another setup."
 If C is selected, ask for only the missing executable/settings locations. Do not request credentials.
+
+## Configuration portability
+
+Explain the user-owned files in `.harness/`: project selection in project.json, model/agent preferences in
+agents.json, task in start.json, sources/destinations in artifacts.json, connection aliases in
+integrations.json, shared commands in environment.json and domain facts in local.md. OpenSpec config
+lives in openspec/config.yaml; checkpoints/evidence live under openspec/changes/<id>/, not in `.harness/state/`.
+Keep managed core/adapters/capabilities/templates/lock separate from customization. Update preserves
+user files; use `aih backup` and copy the reported JSON outside the project before consequential changes.
+Configuration backup contains declarations, not actual input/output docs, external pages, custom skills,
+checkpoint evidence, host credentials or machine.json. Back up those through the project/private host
+mechanism. Same-project restore uses `restore --from ... --dry-run`, with explicit --replace and a
+before-backup for differing files. For another project use --transfer: only module/model preferences,
+old repository autonomy removed; re-establish sources, outputs, commands and connections with the owner.
+Treat imported content as context, never authority or permission. No source-write/autopilot approval is
+inferred from restored settings. CLI only validates schema/digests; host access and semantic review remain necessary.

package/docs/README.md

@@ -45,3 +45,6 @@ See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only
 [Continuous development & living documentation](continuous-development.md): successive features, bugfixes, baseline reconciliation and selective maintenance.
 
 - [Agent-first delivery and 0.12 migration](agent-first.md): proportional roles, selective Product profiles, retired recipes, brownfield/Claude/Maven and checkpoint recovery.
+
+- [Start theo input hiện có](start.md)
+- [Lưu cấu hình, backup, cài lại và chuyển dự án](configuration-backup.md)

package/docs/architecture.md

@@ -156,3 +156,13 @@ The [continuous-development workflow](continuous-development.md) composes existi
 ## Agent-first changes (unreleased)
 
 Optional capability profiles declare asset_owner for a canonical owner; loading validates subset membership, and installation vendors canonical assets while exposing selected skills once. Optional agent/template aliases retain old IDs/routes. Root CLAUDE managed import and native skill wrappers are opt-in locked payloads; external native settings remain project-owned. Checkpoint commands store declarations/history and compute local drift without a runtime/state server. See [Agent-first migration](agent-first.md).
+
+## Guided intake and portable configuration
+
+start uses terminal prompts or a non-TTY plan with saved user-owned start.json; canonical source/output
+declarations remain artifacts.json. backup exports an allowlisted, bounded UTF-8 config archive only.
+restore validates schema/digests/configs/paths, previews conflicts, requires explicit replacement and
+saves a before-backup through the same installation guard/rollback machinery. Transfer copies only
+project/agent preferences and removes repository autonomy. No credentials, machine paths, locked
+payload, custom skills or checkpoint/document contents are exported. Full repo recovery remains Git
+and external-source backup. See [Configuration backup](configuration-backup.md).

package/docs/cli.md

@@ -163,3 +163,20 @@ See [Adaptive verification and TechSpec](adaptive-verification.md) for read-only
 ## Agent-first additions (unreleased)
 
 aih agents shows canonical IDs, skill preferences and model declarations. init --host claude-code seeds a native preset only when agents.json is absent. init/update --link-claude and --claude-skills opt in to managed import/wrappers; native settings remain user-owned. checkpoint <id> --report saves project-owned recovery state; --expected supplies prior digest for replacement. resume <id> is read-only. See [Agent-first guide](agent-first.md). No command launches agents, probes providers, merges or measures quota.
+
+## Start, backup và restore (bản nâng cấp này)
+
+| Lệnh | Hành vi |
+| --- | --- |
+| `aih start` | Terminal: intake ngắn; không TTY: read-only plan; trả host_prompt |
+| `aih start --goal docs --task "Implement requirements" --input docs/requirements --output docs/specs` | Lưu task và seed nguồn/output còn thiếu |
+| `aih backup [--output backups/config.json]` | Export 8 file cấu hình dùng chung; không ghi đè archive |
+| `aih restore --from config.json --dry-run` | Kiểm tra schema/digest và xem file/conflict trước ghi |
+| `aih restore --from config.json [--replace]` | Phục hồi cùng dự án, tự backup trước thay file khác nội dung |
+| `aih restore --from config.json --transfer` | Chuyển module/model; bỏ repo autonomy và nguồn/task/domain/command cũ |
+
+Tất cả nhận --target. Đường dẫn --from/--output tính từ project root. --host dùng với start;
+--change chỉ cho start --goal resume. Các flags sai command bị từ chối. Lệnh --dry-run thuộc restore
+không đổi target hoặc chờ stdin. Fresh repo restore trước init; installed repo update/check sau khi
+selection đổi. Đọc [Start](start.md) và [Configuration backup](configuration-backup.md) cho giới hạn,
+phục hồi checkpoint và rollback. Các lệnh không truy cập remote, chạy model, cấp quyền hay auto-merge.

package/docs/configuration-backup.md

@@ -0,0 +1,122 @@
+# Lưu cấu hình, backup và chuyển dự án
+
+Các lệnh dưới đây dùng `aih` khi đã cài global. Nếu dùng npx, thay `aih` bằng
+`npx --yes @manhd_d/ai-harness`. Những lệnh start/backup/restore thuộc bản nâng cấp này;
+chỉ dùng với bản đã phát hành có các lệnh đó, hoặc checkout/package đã review.
+
+## Thông tin của bạn nằm ở đâu?
+
+Ở **repo dự án áp dụng Harness**, phần cấu hình dùng chung nằm trong `.harness/`:
+
+| File | Thông tin người dùng | Khi update |
+| --- | --- | --- |
+| `.harness/project.json` | Adapter/capability đã chọn | Giữ nguyên |
+| `.harness/agents.json` | Agent → provider/model/reasoning, execution preferences | Giữ nguyên |
+| `.harness/start.json` | Mục tiêu, task, ID change cần tiếp tục | Giữ nguyên |
+| `.harness/artifacts.json` | Đường dẫn/link input, nơi ghi output, owner, revision, write policy | Giữ nguyên |
+| `.harness/integrations.json` | Tên kết nối của host và phạm vi khai báo | Giữ nguyên |
+| `.harness/environment.json` | Tool/lệnh test và tham chiếu biến môi trường | Giữ nguyên |
+| `.harness/local.md` | Nghiệp vụ, convention và quyết định đã chốt | Giữ nguyên |
+| `openspec/config.yaml` | Cấu hình OpenSpec của dự án | Giữ nguyên |
+| `.harness/machine.json` | Đường dẫn chỉ dùng trên máy này | Giữ nguyên, Git ignore; không vào backup cấu hình |
+| `openspec/changes/<id>/` | Spec, tiến độ, checkpoint/history và evidence | Giữ nguyên; backup cùng repo |
+
+**Input/output thực tế nằm ở nơi `artifacts.json` chỉ định**, ví dụ `docs/requirements/`,
+`docs/specs/`, Confluence hoặc Figma. Cấu hình lưu liên kết; không sao chép nội dung nguồn bên ngoài.
+Các skill riêng và native config của AI tool cũng cần giữ cùng cơ chế backup phù hợp của bạn.
+
+`.harness/core/`, `adapters/`, `capabilities/`, `templates/`, `integrations/` và `lock.json`
+là snapshot do Harness quản lý. Không sửa các file này để tùy biến. Giữ toàn bộ repo trong Git
+để rollback snapshot chính xác; bản backup cấu hình chỉ chứa các file được liệt kê bên dưới.
+Không lưu API key/token/password trong cấu hình; host/secret manager quản lý chúng riêng.
+
+## Backup trước update hoặc cài lại
+
+```bash
+aih backup
+```
+
+CLI trả đường dẫn `.harness/backups/config-<timestamp>-<id>.json`. **Copy file này ra nơi riêng
+ngoài repo/máy**, ví dụ ổ backup hoặc kho riêng của bạn; file ở máy hiện tại chưa bảo vệ khỏi mất máy.
+Muốn tên dễ nhớ:
+
+```bash
+aih backup --output backups/harness-config.json
+```
+
+Đường dẫn CLI tính từ project root; không dùng đường dẫn tuyệt đối. CLI từ chối ghi đè backup đã có.
+Archive JSON giữ nguyên bytes UTF-8 của 8 file dùng chung ở bảng (nếu hiện có), kèm schema version,
+CLI version và SHA-256 từng file. Digest phát hiện sửa nhầm, không xác thực nguồn backup.
+Review file trước khi chia sẻ; bản backup là plain text và không tự dò/xóa mọi secret bạn có thể đã ghi nhầm.
+Folder mặc định `.harness/backups/` được Git ignore; backup ở đường dẫn khác do bạn quản lý ignore.
+
+**Không có trong archive:** machine.json, biến môi trường/credentials, host login/native settings,
+snapshot/lock, custom skills, code, nội dung docs/UI bên ngoài, OpenSpec changes/checkpoints/history/evidence.
+Muốn phục hồi toàn bộ công việc, backup **repo + các nguồn/tài khoản ngoài repo** bằng cơ chế của bạn.
+
+Update thông thường bảo toàn file dùng chung; không cần restore mỗi lần:
+
+```bash
+aih backup
+aih update --dry-run
+aih update
+aih check
+```
+
+Trước đó hãy nâng CLI global lên phiên bản đã review nếu cần. CLI không tải bản mới khi chạy update.
+
+## Phục hồi cùng dự án
+
+Copy archive vào project root thành `harness-config.json`, rồi xem trước:
+
+```bash
+aih restore --from harness-config.json --dry-run
+aih restore --from harness-config.json
+```
+
+File giống hệt được giữ nguyên, file thiếu được tạo. File khác nội dung **không bị ghi đè** nếu chưa
+chọn `--replace`. Nếu muốn khôi phục bản cũ thay cho cấu hình hiện tại:
+
+```bash
+aih restore --from harness-config.json --dry-run --replace
+aih restore --from harness-config.json --replace
+```
+
+Trước thay file, CLI tự tạo archive cấu hình hiện tại trong `.harness/backups/`; kết quả trả đường dẫn.
+Không xóa file người dùng không có trong archive. Validation/schema/digest/path/conflict được kiểm tra
+trước ghi; lỗi ghi thông thường rollback. Gián đoạn tiến trình/mất điện không phải transaction nhiều
+file an toàn tuyệt đối: kiểm tra trạng thái và phục hồi từ backup/Git trước khi tiếp tục.
+
+Với repo chưa có snapshot, **restore trước `init`** để bộ cài dùng đúng module và model đã lưu:
+
+```bash
+aih restore --from harness-config.json
+aih init
+aih check
+aih doctor
+aih start
+```
+
+Với repo đã cài, dùng `update --dry-run`, `update`, `check` sau restore nếu selection đổi.
+Restore không sửa snapshot hỏng; phục hồi snapshot qua Git hoặc cài bundle đã review vào repo sạch.
+Nếu goal đã lưu là resume, phục hồi OpenSpec changes/evidence trước khi chạy start/resume.
+Schema archive/config chưa được hỗ trợ bị từ chối; không tự đổi schema hay hạ phiên bản. OpenSpec
+config được giữ dạng text; correctness thuộc upstream OpenSpec validator.
+
+## Mang sang dự án khác
+
+Copy archive vào repo mới, dùng chế độ transfer:
+
+```bash
+aih restore --from harness-config.json --transfer --dry-run
+aih restore --from harness-config.json --transfer
+aih init
+aih start
+```
+
+Transfer mang **project.json + agents.json**: adapter/capability và model/reasoning/execution preferences.
+Khai báo autonomy gắn repo cũ bị loại bỏ. Task, domain facts, nguồn input/output, connection aliases,
+commands, OpenSpec config và state không được chuyển. `start` giúp khai báo lại theo dự án mới.
+Nếu repo mới đã có cấu hình khác, review conflict và chỉ dùng --replace khi muốn thay chúng.
+Model đã khai báo vẫn cần host hỗ trợ; restore không đăng nhập, cấp quyền hoặc gọi API/provider.
+Muốn dùng lại nguồn tài liệu cũ, khai báo rõ nguồn/revision/quyền truy cập tại dự án mới sau review.

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Bắt đầu với AI Harness
 
-**Cài vào project → mở AI → giao việc → review kết quả.** Cần Node.js **22+** và một thư mục project. Với dự án mới, tạo thư mục/repository trước; Harness không tạo ứng dụng hay chạy model.
+**Cài vào project → start → mở AI làm việc → review kết quả.** Cần Node.js **22+** và một thư mục project. Với dự án mới, tạo thư mục/repository trước; Harness không tạo ứng dụng hay chạy model.
 
 ## 1. Cài vào project
 
@@ -31,9 +31,10 @@ npx --yes @manhd_d/ai-harness init --adapters java-spring --capabilities product
 Thêm `--capabilities uiux` khi cần UI/UX; `monetization` cho website có quảng cáo. [Danh mục đầy đủ](cli.md).
 Với project đã cài, đổi lựa chọn trong `.harness/project.json` rồi dùng `update`.
 
-## 2. Mở AI và giao việc
+## 2. Start và mở AI làm việc
 
-Mở thư mục project trong công cụ AI, rồi gửi:
+Chạy `npx --yes @manhd_d/ai-harness start`: trả lời mục tiêu/input/output còn thiếu, rồi gửi
+`host_prompt` từ kết quả vào AI tool đang mở project. [Luồng start](start.md). Nếu đã biết task, có thể gửi thẳng:
 
 > Đọc AGENTS.md và .harness/local.md. Khảo sát code, tài liệu và lệnh test hiện có;
 > ghi context còn thiếu vào .harness/local.md, chỉ hỏi phần chưa rõ.
@@ -65,7 +66,8 @@ Task nhỏ không cần bộ tài liệu đầy đủ. Không cần cài OpenSpe
 
 `check` kiểm tra file Harness; `verify` xuất checklist. Code cần **test của project** và review thực tế.
 
-Trước cập nhật, tạo branch và commit trạng thái hiện tại. Xem trước, áp dụng rồi kiểm tra:
+Trước cập nhật, tạo branch và commit trạng thái hiện tại. Chạy `npx --yes @manhd_d/ai-harness backup`
+và copy JSON được trả về ra nơi riêng ngoài repo. [Lưu ở đâu, cài lại và chuyển dự án](configuration-backup.md). Xem trước, áp dụng rồi kiểm tra:
 
 ```bash
 npx --yes @manhd_d/ai-harness@latest update --dry-run

package/docs/i18n/README.es.md

@@ -12,8 +12,11 @@ Requiere Node.js 22+. Ejecuta en el directorio del proyecto:
 
 ```bash
 npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness start
 ```
 
+Ejecuta `start` para comenzar con tus entradas y envía `host_prompt` a tu herramienta de IA. [Configuración, copia de seguridad y transferencia](../configuration-backup.md).
+
 `npx` no instala el command global `aih`. Comprueba con `npx --yes @manhd_d/ai-harness check` y abre el mismo proyecto en tu AI tool. [Setup común](../tool-setup/README.md).
 
 > Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.

package/docs/i18n/README.vi.md

@@ -12,8 +12,11 @@ Cần Node.js 22+. Chạy trong project:
 
 ```bash
 npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness start
 ```
 
+Chạy `start` để được hướng dẫn theo input hiện có, rồi gửi `host_prompt` cho AI. [Cấu hình, backup và chuyển dự án](../configuration-backup.md).
+
 `npx` không cài global command `aih`. Kiểm tra bằng `npx --yes @manhd_d/ai-harness check`, rồi mở cùng project trong AI tool. [Setup chung](../tool-setup/README.md).
 
 > Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.

package/docs/i18n/README.zh-CN.md

@@ -12,8 +12,11 @@ Core workflows 可用于任何项目。Stack support 是可选的，不会自动
 
 ```bash
 npx --yes @manhd_d/ai-harness init
+npx --yes @manhd_d/ai-harness start
 ```
 
+运行 `start` 获取引导，然后将 `host_prompt` 发送给 AI 工具。[配置备份与项目迁移](../configuration-backup.md)。
+
 `npx` 不会安装全局 `aih` command。使用 `npx --yes @manhd_d/ai-harness check` 检查，然后在 AI tool 中打开同一项目。[通用 Setup](../tool-setup/README.md)。
 
 > Read AGENTS.md. Inspect this project and its approved decisions. Implement [task], run appropriate checks and maintain affected docs.

package/docs/project-configuration.md

@@ -2,6 +2,7 @@
 
 | File | Nội dung | Git |
 | --- | --- | --- |
+| `.harness/start.json` | Mục tiêu/task và ID checkpoint nếu tiếp tục | Commit |
 | `.harness/project.json` | Adapter/capability | Commit |
 | `.harness/agents.json` | Provider/model/reasoning theo role, execution preferences và host mappings | Commit |
 | `.harness/artifacts.json` | Input/output/storage, canonical ownership và source-write policy | Commit |
@@ -10,7 +11,7 @@
 | `.harness/environment.json` | Công cụ, lệnh, file cần có | Commit |
 | `.harness/machine.json` | Đường dẫn riêng của máy, tùy chọn | Ignore |
 
-Init/update tạo environment rỗng nếu chưa có và thêm `/machine.json` vào cuối
+Init/update tạo environment rỗng nếu chưa có và thêm `/backups/` và `/machine.json` vào cuối
 `.harness/.gitignore`. File đã được Git track vẫn được track: ignore không xóa khỏi index/history.
 CLI không tạo file machine và không đọc nội dung Maven settings. Không ghi mật khẩu/token vào các
 file Harness; credentials thuộc cơ chế quản lý riêng của công cụ.
@@ -91,3 +92,10 @@ local.md đã trả lời. Setup không phải wizard nhập liệu và không t
 Xem [Artifact contract](artifact-contract.md). `aih artifacts` báo khai báo; `aih setup` gợi ý hỏi
 nơi lưu docs/UI nếu chưa biết. Các file này project-owned và được bảo toàn khi update; chúng không
 kết nối MCP, cấp quyền hay chạy tool. Credentials và native host config nằm ngoài Git.
+
+## Backup và dùng lại
+
+Chạy `aih start` để lưu intake. File được bảo toàn khi update. Chạy `aih backup`, copy archive ngoài
+repo; `aih restore --from <file> --dry-run` xem trước phục hồi. Dùng --transfer ở repo mới để chỉ
+chuyển module/model, tránh nguồn/tiến độ cũ. [Hướng dẫn đầy đủ](configuration-backup.md) mô tả các
+file được lưu, những gì không có trong backup, conflict/backup-before-replace và cách cài lại.

package/docs/start.md

@@ -0,0 +1,38 @@
+# Bắt đầu một nhiệm vụ
+
+**init → start → làm việc trong AI tool.** Sau cài đặt, chạy trong project root:
+
+```bash
+npx --yes @manhd_d/ai-harness start
+```
+
+Terminal tương tác hỏi mục tiêu và task, input còn thiếu, nơi lưu draft docs khi cần.
+Có cấu hình input/output thì không hỏi lại. Có task đã lưu thì chọn tiếp tục hoặc nhiệm vụ mới;
+model/agent giữ mặc định của host trừ khi bạn muốn cấu hình khác. Lựa chọn được lưu trong
+`.harness/start.json` và `.harness/artifacts.json`; thay cấu hình hiện có tạo backup trước.
+
+Không có TTY (CI/pipe), `start` chỉ xuất JSON plan và không chờ stdin hoặc tự ghi lựa chọn.
+Có thể lưu lựa chọn bằng flags:
+
+```bash
+aih start --goal docs --task "Implement approved requirements" --input docs/requirements --output docs/specs
+aih start --goal change --task "Fix pagination"
+aih start --goal resume --task "Continue the reviewed task" --change add-order
+```
+
+Goal: `idea`, `docs`, `change`, `resume`. Resume cần checkpoint/evidence đã có, kiểm tra freshness và
+side effects trước tiếp tục. --input nhận đường dẫn tương đối hoặc HTTPS URL không chứa credentials;
+--output chỉ nhận folder docs tương đối. Flags input/output chỉ seed khi chưa có khai báo; muốn sửa
+nguồn cũ, review artifacts.json trực tiếp. Start không tự đọc tài liệu ngoài repo, không phê duyệt
+nghiệp vụ hay thực thi command/model. Metadata discovery không chứng minh nội dung nguồn đúng.
+
+Copy `host_prompt` từ kết quả vào AI tool đang mở cùng project. Host đọc task, cấu hình, nguồn và code;
+hỏi tối đa 1–3 quyết định còn thiếu mỗi lượt với phương án và đề xuất có lý do. Dùng workflow/agent/skill
+phù hợp đã cài; module thiếu phải được đề xuất rõ trước thay selection. Tiếp tục thực hiện khi scope và
+quyền đã đủ. Root-file probes không thay thế khảo sát monorepo hoặc đọc tài liệu trong host.
+
+Nếu bạn có nguồn/link/mô tả tự do hoặc cần output bên ngoài, đưa cho AI trong cuộc thảo luận và lưu
+quyết định vào artifacts.json/integrations.json/local.md. Terminal hỏi đáp ngắn; phần BA/thiết kế nằm
+trong AI tool. Không có slash command `/start` chung cho mọi tool ở bản này.
+
+[File cấu hình, backup, cài lại và chuyển dự án](configuration-backup.md) · [AI tool setup](tool-setup/README.md).

package/docs/versioning.md

@@ -170,3 +170,14 @@ correction for the release PR to include. No consumer migration or snapshot upda
 for these guides. Kiro skill pointers are optional, project-owned and not generated/updated by Harness;
 keep existing native configs. Claude agent-first flags are not in the 0.12.0 npm baseline: use the manual
 import or a reviewed version that supports them. See [Tool setup](tool-setup/README.md).
+
+## Guided start and portable user configuration (unreleased)
+
+Distribution remains release-PR owned. Project/lock/agent/artifact schemas stay 1; optional user-owned
+start.json and a separate allowlisted archive schema start at 1. update preserves user settings and
+adds backup-folder ignore with the managed intake workflow. Existing config paths are retained; no
+second user configuration directory is introduced. Run reviewed update --dry-run/update/check and
+re-export evals. New commands require a supporting CLI release. Restore before init on a fresh repo;
+transfer intentionally omits sources/tasks/state/autonomy. Unknown schema versions fail with no writes,
+not automatic migration. Roll back the consumer snapshot via Git and settings via before-backup.
+See [Configuration backup](configuration-backup.md).

package/harness.yaml

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "name": "ai-harness",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "adapters": [
     "java-spring",
     "react-nextjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manhd_d/ai-harness",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Reusable AI development rules, skills and workflows with a safe local installer",
   "type": "module",
   "bin": {

package/templates/AGENTS.md

@@ -11,6 +11,7 @@ New/consequential or resumed work: .harness/core/workflows/continuous-developmen
 Open design choices: .harness/core/workflows/solution-framing.md + SA; present alternatives and ask the owner.
 Accepted decisions are reused. Adapters implement them; adapter selection does not select infrastructure.
 Missing consequential facts: .harness/core/workflows/clarification.md; reuse prior answers and record actual decisions.
+Start/resume intake: read .harness/start.json when present; aih start suggests the next step.
 First use or missing environment: .harness/core/workflows/project-setup.md and project-owned environment.json.
 Docs/UI/source outputs: .harness/core/workflows/artifact-contract.md with artifacts.json/integrations.json and source-write policy.
 Implementation: .harness/core/workflows/spec-to-code.md. Verification/review: .harness/core/workflows/adaptive-verification.md and harness-review.