honestweek 0.2.0 → 0.3.0

package/lib/build.mjs

@@ -16,6 +16,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 
 import { loadConfig } from './config.mjs';
+import { commandConfig } from './config-lookup.mjs';
 import { citedShas, itemRepoLabel, verifyItems, repoMetricsInWindow, commitMessage } from './git.mjs';
 import { loadReaderProfile, ReaderProfileError, READER_FILE } from './reader.mjs';
 import { renderNote } from './emit/client.mjs';
@@ -249,14 +250,22 @@ function normalizeWeek(week, now, config) {
  * On a verification failure it calls io.exit(2) after a clear message and writes
  * nothing. io.exit defaults to process.exit; tests inject a throwing exit.
  */
-export async function runBuild({ cwd = process.cwd(), argv = [], now = new Date(), io = defaultIo(), promptLockHeld = false, transactionFs = {} } = {}) {
+export async function runBuild({ cwd = process.cwd(), argv = [], now = new Date(), io = defaultIo(), promptLockHeld = false, transactionFs = {}, found } = {}) {
   if (!promptLockHeld) {
+    // The config can sit elsewhere (--config, HONESTWEEK_CONFIG, the user-level file); every file
+    // build reads or writes then sits beside it, never in an unrelated folder this ran in.
+    const opened = commandConfig({ command: 'build', cwd, argv, err: io.err });
+    if (opened.error) {
+      io.err(`build: ${opened.error}\n`);
+      return io.exit(1) ?? 1;
+    }
+    ({ cwd, argv } = opened);
     let code;
     try {
       assertNoDigestPending(cwd);
       code = await withPromptLock(
         cwd,
-        () => runBuild({ cwd, argv, now, io: { out: io.out, err: io.err, exit: (value) => value }, promptLockHeld: true, transactionFs }),
+        () => runBuild({ cwd, argv, now, io: { out: io.out, err: io.err, exit: (value) => value }, promptLockHeld: true, transactionFs, found: opened.found }),
         { ensureIgnored: false },
       );
     } catch (err) {
@@ -265,7 +274,7 @@ export async function runBuild({ cwd = process.cwd(), argv = [], now = new Date(
     }
     return code === 0 ? 0 : (io.exit(code) ?? code);
   }
-  const configPath = join(cwd, CONFIG_FILE);
+  const configPath = found?.path ?? join(cwd, CONFIG_FILE);
   const itemsPath = join(cwd, ITEMS_FILE);
 
   let config;

package/lib/config-lookup.mjs

@@ -0,0 +1,179 @@
+// lib/config-lookup.mjs: which honestweek.config.json a command reads, wherever it runs.
+//
+// Claude Code and Codex keep sessions for the whole machine, not per folder, so an agent working
+// in some other project still wants the config the person set up. The lookup, in order:
+//
+//   1. --config <file>, when the command was given one;
+//   2. honestweek.config.json in the folder the command runs in, so every existing setup (and a
+//      scheduled run) reads exactly what it always read;
+//   3. the file the HONESTWEEK_CONFIG environment variable names;
+//   4. the user-level file, ~/.honestweek/honestweek.config.json.
+//
+// Steps 3 and 4 are on only when the entry point (bin/honestweek.mjs) turns them on. A library
+// caller that hands a command its own `cwd`, such as a scheduled run or a test, reads that folder's
+// config and nothing else, as it always has.
+//
+// A command that writes files (the draft, the items, the sidecars, the output) writes them beside
+// the config it read, never into an unrelated folder it happened to run in: `dir` is that folder.
+//
+// Zero runtime dependencies: Node built-ins only.
+
+import { existsSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+export const CONFIG_FILE = 'honestweek.config.json';
+export const CONFIG_ENV = 'HONESTWEEK_CONFIG';
+/** The user-level folder, under the home folder. */
+export const USER_DIR = '.honestweek';
+
+/** The user-level config file for `home` (the home folder by default). */
+export function userConfigPath(home = homedir()) {
+  return join(home, USER_DIR, CONFIG_FILE);
+}
+
+let machine = null;
+
+/**
+ * Turn the machine-wide steps (HONESTWEEK_CONFIG, then the user-level file) on for this process,
+ * and the one stderr line that names the config each command read. The entry point calls this
+ * once; `null` turns them off again (tests).
+ */
+export function setConfigLookup(context = {}) {
+  machine = context ? { env: context.env ?? process.env, home: context.home ?? homedir() } : null;
+}
+
+/** The user-level config file this process would read, or null when the lookup is off. */
+export function lookupUserConfig() {
+  return machine ? userConfigPath(machine.home) : null;
+}
+
+/** Whether anything is at `path`, a broken link included: a config here that can't be read is an
+ *  error to report, never a reason to read another one. */
+const present = (path) => {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const same = (a, b) => {
+  const x = resolve(a);
+  const y = resolve(b);
+  return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+};
+
+/** The config's folder, kept exactly as the caller gave `cwd` when it's the same folder, so a
+ *  message that prints the folder prints what it always printed. */
+const folderOf = (path, cwd) => (same(dirname(path), cwd) ? cwd : dirname(path));
+
+/**
+ * findConfig({ cwd, flag, lookup }) -> { path, dir, source, exists }
+ *
+ * `source` says which step answered: 'flag' (--config), 'folder' (the folder it runs in), 'env'
+ * (HONESTWEEK_CONFIG), 'user' (the user-level file), or 'none' (nowhere; `path` is then this
+ * folder's, where today's messages say it's missing). A step that names a file stops the lookup
+ * even when the file isn't there, so a typo in --config or HONESTWEEK_CONFIG is an error, never a
+ * quiet fall through to another config. `dir` is the folder a writing command writes in.
+ */
+export function findConfig({ cwd = process.cwd(), flag, lookup = machine } = {}) {
+  if (typeof flag === 'string' && flag) {
+    const path = resolve(cwd, flag);
+    return { path, dir: folderOf(path, cwd), source: 'flag', exists: existsSync(path) };
+  }
+  const here = join(cwd, CONFIG_FILE);
+  if (present(here)) return { path: here, dir: cwd, source: 'folder', exists: true };
+  if (lookup) {
+    const named = lookup.env?.[CONFIG_ENV];
+    if (typeof named === 'string' && named.trim()) {
+      const path = resolve(cwd, named.trim());
+      return { path, dir: folderOf(path, cwd), source: 'env', exists: existsSync(path) };
+    }
+    const user = userConfigPath(lookup.home);
+    if (present(user)) return { path: user, dir: folderOf(user, cwd), source: 'user', exists: true };
+  }
+  return { path: here, dir: cwd, source: 'none', exists: false };
+}
+
+/**
+ * takeConfigFlag(argv) -> { config, argv, error }
+ * Takes `--config <file>` (or `--config=<file>`) out of `argv`, so each command's own parser sees
+ * only its own options. `error` is a plain message for a missing value or a repeat.
+ */
+export function takeConfigFlag(argv = []) {
+  const rest = [];
+  let config;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    let value;
+    if (a === '--config') {
+      value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) return { config, argv, error: '--config needs a file.' };
+      i += 1;
+    } else if (typeof a === 'string' && a.startsWith('--config=')) {
+      value = a.slice('--config='.length);
+      if (!value) return { config, argv, error: '--config needs a file.' };
+    } else {
+      rest.push(a);
+      continue;
+    }
+    if (config !== undefined) return { config, argv, error: '--config is given twice.' };
+    config = value;
+  }
+  return { config, argv: rest };
+}
+
+/** `--config <file>` as it was given, for a printed next command to repeat; none without one. */
+export function configAgain(config) {
+  if (config === undefined) return [];
+  return ['--config', /\s/.test(config) ? `"${config}"` : config];
+}
+
+const WHY = {
+  flag: 'named with --config',
+  folder: 'in this folder',
+  env: `named by ${CONFIG_ENV}`,
+  user: 'your user-level config',
+};
+
+/** How a config was found, in words ('in this folder'); null for none. */
+export function configSourceWords(source) {
+  return WHY[source] ?? null;
+}
+
+/** The one line that names the config a command read, and where its files go when that isn't the
+ *  folder it runs in. '' when no config was found (the command's own message says so). */
+export function configLine(command, found, { cwd = process.cwd(), writes = false } = {}) {
+  if (!found || found.source === 'none') return '';
+  const away = writes && !same(found.dir, cwd) ? ` Files it writes go in ${resolve(found.dir)}.` : '';
+  return `honestweek ${command}: config ${found.path} (${WHY[found.source]}).${away}\n`;
+}
+
+/** Write configLine to `err` when the entry point turned the lookup on. */
+export function noteConfig(err, command, found, options) {
+  if (!machine) return;
+  const line = configLine(command, found, options);
+  if (line) err(line);
+}
+
+/**
+ * commandConfig({ command, cwd, argv, err, writes }) -> { found, cwd, argv } or { error }
+ * The lookup as a command uses it: takes --config out of `argv`, finds the config, names it on
+ * stderr, and answers the folder the command works in from here on (the config's own).
+ */
+export function commandConfig({ command, cwd = process.cwd(), argv = [], err = () => {}, writes = true }) {
+  const taken = takeConfigFlag(argv);
+  if (taken.error) return { error: taken.error };
+  const found = findConfig({ cwd, flag: taken.config });
+  noteConfig(err, command, found, { cwd, writes });
+  return { found, cwd: found.dir, argv: taken.argv };
+}
+
+/** What a missing config looks like for `found`, in one line that names the fix. */
+export function missingConfig(found, command = 'honestweek') {
+  if (found.source === 'flag') return `there's no config at ${found.path}, the file --config names.`;
+  if (found.source === 'env') return `there's no config at ${found.path}, the file ${CONFIG_ENV} names.`;
+  return `there's no ${CONFIG_FILE} here, no ${CONFIG_ENV}, and no user-level config. Run ${command} init (add --user to set one up for every folder), or ${command} view to set one up in your browser.`;
+}

package/lib/config.mjs

@@ -407,6 +407,10 @@ export function normalizeConfig(raw, { configDir = process.cwd() } = {}) {
     fail(`"longSessionTokens" must be a whole number from ${LONG_SESSION_MIN} to ${LONG_SESSION_MAX} when present.`);
   }
 
+  // --- saveResults (optional): whether view keeps its results between runs, in a folder beside
+  // this file, and for how long (issue 151). Absent or off, nothing is saved or read.
+  const saveResults = raw.saveResults === undefined ? undefined : normalizeSaveResults(raw.saveResults);
+
   return {
     identity: { authorEmails: authorEmails.map(String) },
     week: { startsOn, timezone },
@@ -423,9 +427,25 @@ export function normalizeConfig(raw, { configDir = process.cwd() } = {}) {
     ...(historyLimitMB !== undefined ? { historyLimitMB } : {}),
     ...(raw.insights === true ? { insights: true } : {}),
     ...(raw.longSessionTokens !== undefined ? { longSessionTokens: raw.longSessionTokens } : {}),
+    ...(saveResults !== undefined ? { saveResults } : {}),
   };
 }
 
+/** How long a saved day may be kept, in days (lib/saved/store.mjs reads the same numbers). */
+export const SAVE_KEEP_DAYS = Object.freeze({ min: 1, max: 36500, default: 365 });
+
+/** { on, keepDays?, history?, otherSessions? }: on, history and otherSessions are true or false,
+ *  and keepDays a whole number of days in range. */
+export function normalizeSaveResults(value) {
+  const msg = `"saveResults" must be { "on": true or false, "keepDays": n, "history": true or false, "otherSessions": true or false } with n from ${SAVE_KEEP_DAYS.min} to ${SAVE_KEEP_DAYS.max} (all but "on" may be left out).`;
+  if (!isPlainObject(value)) fail(msg);
+  if (Object.keys(value).some((k) => !['on', 'keepDays', 'history', 'otherSessions'].includes(k))) fail(msg);
+  for (const k of ['history', 'otherSessions']) if (value[k] !== undefined && typeof value[k] !== 'boolean') fail(msg);
+  if (typeof value.on !== 'boolean') fail(msg);
+  if (value.keepDays !== undefined && !(Number.isInteger(value.keepDays) && value.keepDays >= SAVE_KEEP_DAYS.min && value.keepDays <= SAVE_KEEP_DAYS.max)) fail(msg);
+  return { on: value.on, ...(value.keepDays !== undefined ? { keepDays: value.keepDays } : {}), ...(value.history !== undefined ? { history: value.history } : {}), ...(value.otherSessions !== undefined ? { otherSessions: value.otherSessions } : {}) };
+}
+
 /** The range a long-session limit may take, in tokens of context. */
 export const LONG_SESSION_MIN = 10_000;
 export const LONG_SESSION_MAX = 10_000_000;

package/lib/demo/week.mjs

@@ -25,6 +25,9 @@ import { ciLog, FIXTURES, parseChangelog, repoOf, tapReport, toMarkdown } from '
 import { extraWeek } from './extra.mjs';
 import { createRepo } from './repo.mjs';
 
+/** The made-up project name the demo hides as a private word, so the switch shows something. */
+export const DEMO_TERM = 'lantern';
+
 export const ME = 'you@example.com';
 const AUTHOR = 'You';
 export const WEEK = Object.freeze({ from: '2025-03-10', to: '2025-03-16', timezone: 'UTC' });

package/lib/digest-carry.mjs

@@ -12,6 +12,7 @@ import {
   retiredRow, subjectFingerprint, validateLifecycleWeek, validateRetired, validDateKey, validIso,
 } from './digest-lifecycle.mjs';
 import { assessPublicRendition, createRedactor } from './redact.mjs';
+import { currentCommand } from './invocation.mjs';
 
 export const CARRY_STORE = 'honestweek.carry.json';
 export const CARRY_PENDING = 'honestweek.carry.pending.json';
@@ -329,7 +330,7 @@ export function removeCarryPending(cwd, fs = { unlinkSync }) {
 
 export function assertNoCarryPending(cwd) {
   if (existsSync(join(cwd, CARRY_PENDING))) {
-    throw new Error(`${CARRY_PENDING} is present; run honestweek digest recover before continuing.`);
+    throw new Error(`${CARRY_PENDING} is present; run ${currentCommand()} digest recover before continuing.`);
   }
 }
 
@@ -367,7 +368,7 @@ export function recoverCarryPending({ cwd, config, outputPath, outputBinding, pe
     return { recovered: true, action: 'completed' };
   }
   if (!outputTarget && carryPrior) {
-    throw new Error('carry pending has no matching output; run honestweek digest recover --discard-pending after verifying the prior output.');
+    throw new Error(`carry pending has no matching output; run ${currentCommand()} digest recover --discard-pending after verifying the prior output.`);
   }
   throw new Error('carry pending hashes are in an unknown state; no state was changed.');
 }

package/lib/digest-store.mjs

@@ -9,6 +9,7 @@ import {
 } from './digest-schema.mjs';
 import { digestItemIdentity, sha256 } from './prompt-identity.mjs';
 import { DETECTOR_ORDER, REPLACEABLE_DETECTORS } from './prompt-privacy.mjs';
+import { currentCommand } from './invocation.mjs';
 import {
   addWeeks, exactObject as exact, validateLifecycleEntry, validateLifecycleWeek,
   validateRenewal, validateRetired, validIso,
@@ -392,7 +393,7 @@ export function validateDigestLane(lane, config) {
 
 export function readDigestReview(cwd, config, { historical = false } = {}) {
   const path = join(cwd, DIGEST_STORE);
-  if (!existsSync(path)) throw new Error(`${DIGEST_STORE} not found; run honestweek digest prepare.`);
+  if (!existsSync(path)) throw new Error(`${DIGEST_STORE} not found; run ${currentCommand()} digest prepare.`);
   let value;
   try { value = JSON.parse(readFileSync(path, 'utf8')); } catch (error) { throw new Error(`${DIGEST_STORE} is not valid JSON (${error.message}).`); }
   return validateDigestReview(value, config, { historical });
@@ -443,7 +444,7 @@ export function readDigestPending(cwd, { optional = false } = {}) {
 }
 
 export function assertNoDigestPending(cwd) {
-  if (existsSync(join(cwd, DIGEST_PENDING))) throw new Error(`${DIGEST_PENDING} is present; run honestweek digest prepare to recover before any other command.`);
+  if (existsSync(join(cwd, DIGEST_PENDING))) throw new Error(`${DIGEST_PENDING} is present; run ${currentCommand()} digest prepare to recover before any other command.`);
 }
 
 export function assertRecoverableDigestPending(cwd, pending) {

package/lib/digest.mjs

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { loadConfig } from './config.mjs';
+import { commandConfig, configAgain, takeConfigFlag } from './config-lookup.mjs';
 import { localDateInTimezone, localDateRangeInstants, resolveWeek } from './resolve-week.mjs';
 import { resolvePromptRoots, scanPromptSources } from './prompt-adapters.mjs';
 import { mergePromptStore, PROMPT_GITIGNORE, readPromptStore, writePromptStore } from './prompt-store.mjs';
@@ -24,6 +25,7 @@ import {
 import { addWeeks } from './digest-lifecycle.mjs';
 import { recoverConfiguredCarry } from './carry-recovery.mjs';
 import { verifyCarryReceipts } from './carry-receipts.mjs';
+import { currentCommand } from './invocation.mjs';
 
 function defaultIo() {
   return { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s), exit: (code) => process.exit(code) };
@@ -59,7 +61,7 @@ function nextPage(args, offset) {
     if (args[i] === '--offset') { i += 1; continue; }
     kept.push(args[i]);
   }
-  return `honestweek digest candidates${kept.length ? ` ${kept.join(' ')}` : ''} --offset ${offset}`;
+  return `${currentCommand()} digest candidates${kept.length ? ` ${kept.join(' ')}` : ''} --offset ${offset}`;
 }
 
 function positionalArgs(args, optionsWithValues) {
@@ -119,7 +121,7 @@ async function prepare({ cwd, config, args, now, roots, io, transactionFs = {},
     phase = 'pending removal';
     removeDigestPending(cwd, transactionFs.remove);
   } catch (error) {
-    throw new Error(`digest transaction remains pending after the ${phase} write failed (${error.message}); that state may have changed, so rerun honestweek digest prepare.`);
+    throw new Error(`digest transaction remains pending after the ${phase} write failed (${error.message}); that state may have changed, so rerun ${currentCommand()} digest prepare.`);
   }
   const omitted = DIGEST_CATEGORIES.map((category) => {
     const counts = lane.withheld.byCategory[category];
@@ -137,7 +139,7 @@ async function loadCanonical({ cwd, config, args, now, roots }) {
     cwd, config, week: { start: week.start, end: week.end }, now, roots,
     hasGoals: existsSync(join(cwd, 'honestweek.objectives.json')),
   });
-  if (loaded.lane?.version !== 2) throw new Error('balanced digest is not prepared; run honestweek digest prepare.');
+  if (loaded.lane?.version !== 2) throw new Error(`balanced digest is not prepared; run ${currentCommand()} digest prepare.`);
   return { review: loaded.review, lane: loaded.lane, week };
 }
 
@@ -148,7 +150,7 @@ function normalizeCategory(value) {
   return value;
 }
 
-async function candidates({ cwd, config, args, now, roots, io }) {
+async function candidates({ cwd, config, args, now, roots, io, again = [] }) {
   const { review } = await loadCanonical({ cwd, config, args, now, roots });
   const category = normalizeCategory(flag(args, '--category'));
   const decision = flag(args, '--decision') ?? 'all';
@@ -170,7 +172,7 @@ async function candidates({ cwd, config, args, now, roots, io }) {
   }
   const shown = Math.min(limit, Math.max(0, rows.length - offset));
   const remaining = Math.max(0, rows.length - offset - shown);
-  io.out(`digest candidates: showing ${shown ? offset + 1 : 0}-${shown ? offset + shown : 0} of ${rows.length}; remaining ${remaining}.${remaining ? ` Next: ${nextPage(args, offset + shown)}.` : ''}\n`);
+  io.out(`digest candidates: showing ${shown ? offset + 1 : 0}-${shown ? offset + shown : 0} of ${rows.length}; remaining ${remaining}.${remaining ? ` Next: ${nextPage([...args, ...again], offset + shown)}.` : ''}\n`);
   return 0;
 }
 
@@ -264,7 +266,7 @@ async function control({ cwd, config, command, args, now, roots, io, transaction
     const count = review.candidates.length;
     await prepare({ cwd, config, args, now, roots, io, transactionFs,
       priorReviewOverride: bulkDeletedReview(review, now), quiet: true });
-    io.out(`digest delete: removed ${count} private digest item(s) and left no-text tombstones. This cannot recall honestweek.prompt-items.json or the built page. Run honestweek validate, then honestweek build; remove the local output now if needed.\n`);
+    io.out(`digest delete: removed ${count} private digest item(s) and left no-text tombstones. This cannot recall honestweek.prompt-items.json or the built page. Run ${currentCommand()} validate, then ${currentCommand()} build; remove the local output now if needed.\n`);
     return 0;
   }
   const [prefix] = positions;
@@ -279,12 +281,12 @@ async function control({ cwd, config, command, args, now, roots, io, transaction
     : controlledReview(review, candidate, command, now);
   await prepare({ cwd, config, args, now, roots, io, transactionFs, priorReviewOverride: override, quiet: true });
   if (command === 'carry-forward') {
-    io.out(`digest carry-forward: ${candidate.itemRef.slice(0, 12)} is renewed for ${addWeeks(review.week.start, 1)} only. Renewal cannot override receipts or privacy. Run honestweek validate, then honestweek build.\n`);
+    io.out(`digest carry-forward: ${candidate.itemRef.slice(0, 12)} is renewed for ${addWeeks(review.week.start, 1)} only. Renewal cannot override receipts or privacy. Run ${currentCommand()} validate, then ${currentCommand()} build.\n`);
   } else if (command === 'delete') {
-    io.out(`digest delete: removed private ${candidate.category} item ${candidate.itemRef.slice(0, 12)} and left a no-text tombstone. This cannot recall honestweek.prompt-items.json or the built page. Run honestweek validate, then honestweek build; remove the local output now if needed.\n`);
+    io.out(`digest delete: removed private ${candidate.category} item ${candidate.itemRef.slice(0, 12)} and left a no-text tombstone. This cannot recall honestweek.prompt-items.json or the built page. Run ${currentCommand()} validate, then ${currentCommand()} build; remove the local output now if needed.\n`);
   } else {
     const next = readDigestReview(cwd, config).candidates.find((value) => value.itemRef === candidate.itemRef);
-    io.out(`digest ${command}: ${candidate.itemRef.slice(0, 12)} is ${command === 'keep' ? 'kept' : 'hidden'}; decision ${next.decision}. ${command === 'keep' ? 'Keep cannot override receipt or privacy gates. ' : ''}Run honestweek validate, then honestweek build.\n`);
+    io.out(`digest ${command}: ${candidate.itemRef.slice(0, 12)} is ${command === 'keep' ? 'kept' : 'hidden'}; decision ${next.decision}. ${command === 'keep' ? 'Keep cannot override receipt or privacy gates. ' : ''}Run ${currentCommand()} validate, then ${currentCommand()} build.\n`);
   }
   return 0;
 }
@@ -378,7 +380,7 @@ async function resetTombstones({ cwd, config, args, now, io, transactionFs = {}
     next.generatedAt = now.toISOString();
     writePromptStore(cwd, next, transactionFs.resetPromptStore);
   }
-  io.out(`digest reset-tombstones: removed ${carryRemoved + reviewRemoved} digest blocker(s) and ${promptRemoved} prompt blocker(s). No live text, public lane, or output was changed. Reset cannot recall or repair an already built, copied, or published artifact. Run honestweek digest prepare, honestweek validate, then honestweek build.\n`);
+  io.out(`digest reset-tombstones: removed ${carryRemoved + reviewRemoved} digest blocker(s) and ${promptRemoved} prompt blocker(s). No live text, public lane, or output was changed. Reset cannot recall or repair an already built, copied, or published artifact. Run ${currentCommand()} digest prepare, ${currentCommand()} validate, then ${currentCommand()} build.\n`);
   return 0;
 }
 
@@ -394,15 +396,20 @@ async function recover({ cwd, config, args, io, transactionFs = {}, quiet = fals
 }
 
 export async function runDigest({ cwd = process.cwd(), argv = [], now = new Date(), io = defaultIo(), roots, transactionFs } = {}) {
-  const [command, ...args] = argv;
+  const taken = takeConfigFlag(argv);
+  const [command, ...args] = taken.argv;
   // Help anywhere in argv, not just first: `digest prepare --help` used to run
   // a real prepare (loading config, taking the lock, scanning transcripts).
   if (!command || argv.some((a) => a === '-h' || a === '--help')) {
-    io.out('Usage: honestweek digest <prepare|candidates|explain|keep|hide|delete|carry-forward|recover|reset-tombstones> [options]\n');
+    io.out(`Usage: ${currentCommand()} digest <prepare|candidates|explain|keep|hide|delete|carry-forward|recover|reset-tombstones> [options] [--config <file>]\n`);
     return 0;
   }
+  if (taken.error) { io.err(`digest: ${taken.error}\n`); return io.exit(1) ?? 1; }
+  // Every digest file sits beside the config, wherever the lookup found it.
+  const opened = commandConfig({ command: 'digest', cwd, argv, err: io.err });
+  cwd = opened.cwd;
   let config;
-  try { config = loadConfig(join(cwd, 'honestweek.config.json')); }
+  try { config = loadConfig(opened.found.path); }
   catch (error) { io.err(`digest: ${error.message}\n`); return io.exit(1) ?? 1; }
   const selectedRoots = roots ?? resolvePromptRoots();
   try {
@@ -419,7 +426,7 @@ export async function runDigest({ cwd = process.cwd(), argv = [], now = new Date
         assertNoCarryPending(cwd);
       }
       if (command === 'prepare') return prepare({ cwd, config, args, now, roots: selectedRoots, io, transactionFs });
-      if (command === 'candidates') return candidates({ cwd, config, args, now, roots: selectedRoots, io });
+      if (command === 'candidates') return candidates({ cwd, config, args, now, roots: selectedRoots, io, again: configAgain(taken.config) });
       if (command === 'explain') return explain({ cwd, config, args, now, roots: selectedRoots, io });
       if (command === 'reset-tombstones') return resetTombstones({ cwd, config, args, now, io, transactionFs });
       if (command === 'keep' || command === 'hide' || command === 'delete' || command === 'carry-forward') {

package/lib/discover.mjs

@@ -15,12 +15,14 @@
 // Zero runtime dependencies: Node built-ins + system git only.
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { join } from 'node:path';
 
 import { loadConfig } from './config.mjs';
+import { commandConfig } from './config-lookup.mjs';
 import { createRedactor } from './redact.mjs';
 import { resolveWeek, localDateInTimezone, WeekResolutionError } from './resolve-week.mjs';
 import { commitsInWindow, gitExec } from './git.mjs';
+import { checkoutOf, reachesDisplay } from './repo-identity.mjs';
 import { adaptSessions } from './claude-adapter.mjs';
 import { discoverHandoffs } from './handoffs.mjs';
 
@@ -48,24 +50,14 @@ function parseWeekArg(argv) {
   return undefined;
 }
 
-/** A path made comparable: absolute, no trailing separator, case-folded on Windows. */
-function comparablePath(p) {
-  let out = resolve(p);
-  while (out.length > 1 && (out.endsWith(sep) || out.endsWith('/')) && !/^[A-Za-z]:[\\/]$/.test(out)) out = out.slice(0, -1);
-  return process.platform === 'win32' ? out.toLowerCase() : out;
-}
-
-/** True when `folder` is `repo` itself or anywhere inside it. */
-export function isSameOrInside(folder, repo) {
-  const f = comparablePath(folder);
-  const r = comparablePath(repo);
-  if (f === r) return true;
-  return f.startsWith(r.endsWith(sep) ? r : r + sep);
-}
+/** What discover says when it can't ask git whether the draft is committed (issue 161). */
+export const CANT_CHECK_DRAFT = `discover: check that ${DRAFT_FILE}, your private draft, was never committed to git. Listing it in .gitignore doesn't remove it from git if it was committed before, and honestweek can't check for you here because of your display-only setting. Run git ls-files ${DRAFT_FILE}. If it prints the file name, run git rm --cached ${DRAFT_FILE}.\n`;
 
 /** Append DRAFT_FILE to .gitignore idempotently; warn loudly if it is tracked.
- *  When `cwd` is a display-role repo, git is never asked (AGENTS.md invariant 4). */
-export function ensureDraftGitignored(cwd, io, { isDisplay = false } = {}) {
+ *  When git running in `cwd` would reach a display-only folder, git is never asked (AGENTS.md
+ *  invariant 4), and it says how to check by hand instead. Outside any checkout (`inRepo`
+ *  false) there's nothing to check, so it asks git nothing and says nothing. */
+export function ensureDraftGitignored(cwd, io, { isDisplay = false, inRepo = true } = {}) {
   const giPath = join(cwd, '.gitignore');
   const existing = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
   if (!existing.split(/\r?\n/).some((l) => l.trim() === DRAFT_FILE)) {
@@ -73,10 +65,14 @@ export function ensureDraftGitignored(cwd, io, { isDisplay = false } = {}) {
     writeFileSync(giPath, `${prefix}${DRAFT_FILE}\n`);
   }
   // Warn if the draft is already tracked in git (a privacy hazard).
-  if (isDisplay) return;
+  if (!inRepo) return;
+  if (isDisplay) {
+    io.err(CANT_CHECK_DRAFT);
+    return;
+  }
   try {
     const tracked = gitExec(['ls-files', '--', DRAFT_FILE], { repo: cwd, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    if (tracked) io.err(`discover: WARNING — ${DRAFT_FILE} is tracked in git. It must never be committed.\n`);
+    if (tracked) io.err(`discover: WARNING: ${DRAFT_FILE} is tracked in git. It must never be committed.\n`);
   } catch {
     /* not a git repo / git unavailable — nothing to warn about */
   }
@@ -105,9 +101,17 @@ export async function runDiscover({
   adapter = adaptSessions,
   gitWindow = commitsInWindow,
 } = {}) {
+  // The config can sit elsewhere (--config, HONESTWEEK_CONFIG, the user-level file); the draft
+  // is written beside it, never into an unrelated folder this ran in.
+  const opened = commandConfig({ command: 'discover', cwd, argv, err: io.err });
+  if (opened.error) {
+    io.err(`discover: ${opened.error}\n`);
+    return io.exit(1) ?? 1;
+  }
+  ({ cwd, argv } = opened);
   let config;
   try {
-    config = loadConfig(join(cwd, 'honestweek.config.json'));
+    config = loadConfig(opened.found.path);
   } catch (err) {
     io.err(`discover: ${err.message}\n`);
     return io.exit(1) ?? 1;
@@ -175,8 +179,10 @@ export async function runDiscover({
   const redacted = redactor.deepRedact(digest);
   // A new draft is readable only by its owner on POSIX; a rewrite keeps the mode it has.
   writeFileSync(join(cwd, DRAFT_FILE), `${JSON.stringify(redacted, null, 2)}\n`, { mode: 0o600 });
-  const cwdIsDisplay = (config.repos ?? []).some((r) => r.role === 'display' && isSameOrInside(cwd, r.resolvedPath ?? r.path));
-  ensureDraftGitignored(cwd, io, { isDisplay: cwdIsDisplay });
+  // Git isn't asked where it would reach a display-only folder, the same test Settings'
+  // configTrackState makes, nor outside any checkout, where there's nothing to track.
+  const displayPaths = (config.repos ?? []).filter((r) => r.role === 'display').map((r) => r.resolvedPath ?? r.path);
+  ensureDraftGitignored(cwd, io, { isDisplay: reachesDisplay(displayPaths)(cwd), inRepo: checkoutOf(cwd) !== null });
 
   const publicCount = sessions.length - privateCount;
   io.out(

package/lib/emit/index.mjs

@@ -8,7 +8,7 @@
 // publishes it themselves.
 
 import { readFileSync, existsSync, mkdirSync } from 'node:fs';
-import { isAbsolute, join, dirname } from 'node:path';
+import { isAbsolute, join, dirname, resolve } from 'node:path';
 
 import { OUTPUT_MODES, DEFAULT_OUTPUT_FILES } from '../config.mjs';
 import { renderSite } from '../site/emit-site.mjs';
@@ -29,7 +29,9 @@ export async function resolvePrimaryOutputPath(config, { cwd = process.cwd() } =
     const loaded = await loadSiteAdapter(config.output.adapter);
     return isAbsolute(loaded.artifact) ? loaded.artifact : join(cwd, loaded.artifact);
   }
-  return config?.output?.file || DEFAULT_OUTPUT_FILES[config?.output?.mode ?? 'digest'];
+  // The same folder prepareEmission writes to, so carry recovery hashes the file build wrote.
+  const file = config?.output?.file || DEFAULT_OUTPUT_FILES[config?.output?.mode ?? 'digest'];
+  return isAbsolute(file) ? file : join(cwd, file);
 }
 
 /** The number of items rendered by a report model (loose + grouped). */
@@ -102,10 +104,19 @@ export function renderFor(mode, reportModel, config) {
   return emitter.render(reportModel, config);
 }
 
+/** Whether two folders are the same one, ignoring case on Windows. */
+function sameFolder(a, b) {
+  const x = resolve(a);
+  const y = resolve(b);
+  return process.platform === 'win32' ? x.toLowerCase() === y.toLowerCase() : x === y;
+}
+
 /**
  * emit(reportModel, config, { cwd }) -> { path, mode, bytes, items }
- * Dispatches strictly by config.output.mode and writes one local file. `cwd` (the
- * target root) is used only by the site mode to resolve the adapter's artifact path.
+ * Dispatches strictly by config.output.mode and writes one local file. `cwd` is the config's
+ * folder: a relative output.file resolves against it, as the site mode's artifact path does, so
+ * the output lands beside the config the command found (issue 194). When that's the folder the
+ * process runs in, the path stays as written, so what build prints doesn't change.
  */
 export function prepareEmission(reportModel, config, { cwd = process.cwd() } = {}) {
   const mode = config?.output?.mode ?? 'digest';
@@ -118,10 +129,11 @@ export function prepareEmission(reportModel, config, { cwd = process.cwd() } = {
     throw new Error('emit: site mode must be emitted via emitSite (async), not emit.');
   }
 
-  const file = config?.output?.file || DEFAULT_OUTPUT_FILES[mode];
-  if (!file) {
+  const configured = config?.output?.file || DEFAULT_OUTPUT_FILES[mode];
+  if (!configured) {
     throw new Error(`emit: no output file configured for mode ${JSON.stringify(mode)} and no default available.`);
   }
+  const file = isAbsolute(configured) || sameFolder(cwd, process.cwd()) ? configured : join(cwd, configured);
 
   let content;
   if (mode === 'changelog') {

package/lib/harvest.mjs

@@ -17,11 +17,14 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { loadConfig } from './config.mjs';
+import { commandConfig } from './config-lookup.mjs';
 import { currentCommand } from './invocation.mjs';
 
 const CONFIG_FILE = 'honestweek.config.json';
 const DRAFT_FILE = 'honestweek.draft.json';
 const HARVEST_FILE = 'honestweek.harvest.json';
+/** The .gitignore line for harvest's sidecar, which init also writes when it sets up a folder. */
+export const HARVEST_GITIGNORE = Object.freeze([HARVEST_FILE]);
 
 // Common capitalized English words / sentence-starters to ignore — high-noise,
 // low-signal. The harvester is advisory, so over-inclusion here only trims noise.
@@ -52,6 +55,13 @@ function isCandidate(w) {
   return false;
 }
 
+/** True when a word is shaped like a name worth proposing and isn't a common English word:
+ *  harvest's rules, in any alphabet, so José and Łukasz count. Settings' "Suggest words" uses it. */
+export function isNameShaped(w) {
+  if ([...w].length < 3 || STOP.has(w.toLowerCase())) return false;
+  return /^\p{Lu}{3,}$/u.test(w) || /\p{Ll}\p{Lu}/u.test(w) || /^\p{Lu}\p{Ll}+$/u.test(w);
+}
+
 /** Count proper-noun-shaped tokens in a string, minus an exclude set + STOP. */
 export function harvestNouns(text, { exclude = new Set() } = {}) {
   const counts = new Map();
@@ -119,9 +129,17 @@ function ensureHarvestGitignored(cwd) {
  * sidecar, and prints ONLY the count.
  */
 export async function runHarvest({ cwd = process.cwd(), argv = [], now = new Date(), io = defaultIo() } = {}) {
+  // The config can sit elsewhere (--config, HONESTWEEK_CONFIG, the user-level file); harvest's
+  // files then sit beside it, never in an unrelated folder this ran in.
+  const opened = commandConfig({ command: 'harvest', cwd, argv, err: io.err });
+  if (opened.error) {
+    io.err(`harvest: ${opened.error}\n`);
+    return io.exit(1) ?? 1;
+  }
+  ({ cwd, argv } = opened);
   let config;
   try {
-    config = loadConfig(join(cwd, CONFIG_FILE));
+    config = loadConfig(opened.found.path);
   } catch (err) {
     io.err(`harvest: ${err.message}\n`);
     return io.exit(1) ?? 1;