@aopslabs/aops 0.3.31 → 0.3.33

package/dist/commands/memory.js

@@ -2597,6 +2597,7 @@ function applyMemoryContextOptions(cmd) {
     cmd.option('--scope-id <id>', 'Canonical owner scope override');
     cmd.option('--project-id <id>', 'Project id used to resolve scope and memory ownership');
     cmd.option('--project-name <name>', 'Project name override for repo-aware scope resolution');
+    cmd.option('--project-slug <slug>', 'Project slug override for repo-aware scope resolution');
     cmd.option('--tenant-id <id>', 'Tenant id header (x-tenant-id)');
     cmd.option('--locale <locale>', 'Locale header (x-locale)');
     cmd.option('--fallback-locale <locale>', 'Fallback locale header (x-fallback-locale)');
@@ -3120,7 +3121,7 @@ Advanced surface:
             'AI/automation varsayilani short memory olmalidir; durable `note` ve sticky `rule` yalnizca operator/human acikca isterse yazilmalidir.',
             '`--mode` kickoff/resume/decision/blocker/closeout/rule kisayollaridir; `note` icin `--kind note --durability short|durable|sticky` kullan.',
             "PowerShell icinde @file content pointerlarini tirnakla yaz: `--content '@tmp/checkpoint.md'`.",
-            'Memory backend SERVER-FIRST hosted Agentspace memory-item ops uzerindendir (create/write/read hepsi hosted); local `.aops/agentspace/memory` source-of-truth DEGIL, yalnizca read-only file-search cache.',
+            'Memory backend SERVER-FIRST hosted Agentspace memory-item ops uzerindendir (create/write/read hepsi hosted); local `.aops-cache/agentspace/memory` source-of-truth DEGIL, yalnizca read-only file-search cache.',
             '`handoff` gorunumu canonical `resume` kayitlarinin alias\'idir.',
             '--content zorunludur; @file ile dosyadan okunur (or paste inline); uzun canonical icerik yerine --next-read-ref/--source-ref ile pointer ver.',
             'Soft TTL silme yapmaz; expired memory tutulur ama retrieval tarafinda asagi itilir.',

package/dist/commands/pm/index.js

@@ -402,6 +402,7 @@ function addIssueCommands(cmd) {
         .option('--severity <value>', 'Optional issue severity filter')
         .option('--source <value>', 'Optional issue source filter')
         .option('--tag <value>', 'Repeatable issue tag filter', collectRepeatedOption, [])
+        .option('--limit <count>', 'Optional positive maximum result count')
         .action(async (options) => {
         await runPmIssueList(options);
     }));
@@ -461,10 +462,11 @@ function addFeedbackCommands(cmd) {
         .option('--sprint <id>', 'Optional sprint id filter')
         .option('--utask <id>', 'Optional sprint microtask id filter')
         .option('--status <value>', 'Optional feedback status filter')
-        .option('--type <value>', 'Optional feedback type filter')
+        .option('--type <value>', 'Optional feedback type filter: refactor, bug, improvement, warning, observation, other')
         .option('--severity <value>', 'Optional feedback severity filter')
-        .option('--source <value>', 'Optional feedback source filter')
+        .option('--source <value>', 'Optional feedback source filter: human, agent, automation')
         .option('--tag <value>', 'Repeatable feedback tag filter', collectRepeatedOption, [])
+        .option('--limit <count>', 'Optional positive maximum result count')
         .action(async (options) => {
         await runPmFeedbackList(options);
     }));
@@ -481,9 +483,9 @@ function addFeedbackCommands(cmd) {
         .requiredOption('--title <title>', 'Feedback title')
         .option('--description <text>', 'Feedback description')
         .option('--status <value>', 'Initial feedback status')
-        .option('--type <value>', 'Feedback type')
+        .option('--type <value>', 'Feedback type: refactor, bug, improvement, warning, observation, other')
         .option('--severity <value>', 'Feedback severity')
-        .option('--source <value>', 'Feedback source')
+        .option('--source <value>', 'Feedback source: human, agent, automation')
         .option('--task <id>', 'Linked kanban task id')
         .option('--sprint <id>', 'Linked sprint id')
         .option('--utask <id>', 'Linked sprint microtask id')
@@ -499,9 +501,9 @@ function addFeedbackCommands(cmd) {
         .option('--title <title>', 'Updated feedback title')
         .option('--description <text>', 'Updated feedback description')
         .option('--status <value>', 'Updated feedback status')
-        .option('--type <value>', 'Updated feedback type')
+        .option('--type <value>', 'Updated feedback type: refactor, bug, improvement, warning, observation, other')
         .option('--severity <value>', 'Updated feedback severity')
-        .option('--source <value>', 'Updated feedback source')
+        .option('--source <value>', 'Updated feedback source: human, agent, automation')
         .option('--task <id>', 'Updated kanban task id link')
         .option('--sprint <id>', 'Updated sprint id link')
         .option('--utask <id>', 'Updated sprint microtask id link')
@@ -533,7 +535,7 @@ function addReviewRequestCommands(cmd) {
         .option('--utask <id>', 'Optional sprint microtask id filter')
         .option('--status <value>', 'Optional review-request status filter')
         .option('--priority <value>', 'Optional review-request priority filter')
-        .option('--source <value>', 'Optional review-request source filter')
+        .option('--source <value>', 'Optional review-request source filter: human, agent, automation, collab')
         .option('--target-agent <id>', 'Optional reviewer agent filter')
         .option('--target-slot <slot>', 'Optional reviewer role slot filter')
         .option('--parent <id>', 'Optional parent review-request id filter')
@@ -559,7 +561,7 @@ function addReviewRequestCommands(cmd) {
         .option('--reference <value>', 'Repeatable reference pointer', collectRepeatedOption, [])
         .option('--status <value>', 'Initial status: requested, in_review, responded, accepted, changes_requested, closed, cancelled')
         .option('--priority <value>', 'Priority: low, medium, high, critical (default medium)')
-        .option('--source <value>', 'Source: agent, operator, collab, sync, import, manual')
+        .option('--source <value>', 'Source: human, agent, automation, collab')
         .option('--task <id>', 'Linked kanban task id')
         .option('--sprint <id>', 'Linked sprint id')
         .option('--utask <id>', 'Linked sprint microtask id')
@@ -581,7 +583,7 @@ function addReviewRequestCommands(cmd) {
         .option('--instructions <text>', 'Updated reviewer instructions')
         .option('--reference <value>', 'Repeatable reference pointer patch', collectRepeatedOption, [])
         .option('--priority <value>', 'Updated priority')
-        .option('--source <value>', 'Updated source')
+        .option('--source <value>', 'Updated source: human, agent, automation, collab')
         .option('--task <id>', 'Updated kanban task id link')
         .option('--sprint <id>', 'Updated sprint id link')
         .option('--utask <id>', 'Updated sprint microtask id link')

package/dist/commands/pm/projectman.js

@@ -1856,6 +1856,15 @@ function parseOptionalInteger(value, label) {
     }
     return normalized;
 }
+function parseOptionalPositiveInteger(value, label) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const parsed = typeof value === 'number' ? value : Number(String(value));
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return parsed;
+}
 function buildCommandEnvelope(params) {
     return {
         command: params.command,
@@ -5342,6 +5351,7 @@ export async function runPmIssueList(options = {}) {
         const severity = normalizeNonEmpty(options.severity);
         const source = normalizeNonEmpty(options.source);
         const tags = normalizeArrayValues(options.tag);
+        const limit = parseOptionalPositiveInteger(options.limit, '--limit');
         if (status)
             input.status = status;
         if (severity)
@@ -5350,10 +5360,20 @@ export async function runPmIssueList(options = {}) {
             input.source = source;
         if (tags)
             input.tags = tags;
-        const payload = await invokeProjectmanTool(execution, options, {
+        const rawPayload = await invokeProjectmanTool(execution, options, {
             toolId: 'projectman.issue.list',
             input,
         });
+        const records = toRecordArray(unwrapHostedToolResult(rawPayload));
+        const visibleRecords = limit === undefined ? records : records.slice(0, limit);
+        const payload = {
+            response: {
+                data: visibleRecords,
+                count: records.length,
+                shown: visibleRecords.length,
+                hasMore: visibleRecords.length < records.length,
+            },
+        };
         emitCommandResult(options, {
             command: 'pm.issue.list',
             toolId: 'projectman.issue.list',
@@ -5570,6 +5590,7 @@ export async function runPmFeedbackList(options = {}) {
         const severity = normalizeNonEmpty(options.severity);
         const source = normalizeNonEmpty(options.source);
         const tags = normalizeArrayValues(options.tag);
+        const limit = parseOptionalPositiveInteger(options.limit, '--limit');
         if (status)
             input.status = status;
         if (type)
@@ -5580,10 +5601,20 @@ export async function runPmFeedbackList(options = {}) {
             input.source = source;
         if (tags)
             input.tags = tags;
-        const payload = await invokeProjectmanTool(execution, options, {
+        const rawPayload = await invokeProjectmanTool(execution, options, {
             toolId: 'projectman.feedback.list',
             input,
         });
+        const records = toRecordArray(unwrapHostedToolResult(rawPayload));
+        const visibleRecords = limit === undefined ? records : records.slice(0, limit);
+        const payload = {
+            response: {
+                data: visibleRecords,
+                count: records.length,
+                shown: visibleRecords.length,
+                hasMore: visibleRecords.length < records.length,
+            },
+        };
         emitCommandResult(options, {
             command: 'pm.feedback.list',
             toolId: 'projectman.feedback.list',

package/dist/commands/project.js

@@ -236,8 +236,8 @@ function normalizeMigrationLocalRoot(value) {
     if (normalized === '.' || normalized.startsWith('../') || normalized === '..') {
         throw new Error('--local-root must stay inside the repo.');
     }
-    if (!normalized.startsWith('.aops/projects/')) {
-        throw new Error('--local-root must be under .aops/projects/<slug>.');
+    if (!normalized.startsWith('.aops-cache/projects/')) {
+        throw new Error('--local-root must be under .aops-cache/projects/<slug>.');
     }
     return normalized;
 }
@@ -514,7 +514,7 @@ async function applyLocalRootMigration(params) {
     }
     const repoRoot = params.plan.repoRoot;
     const archiveRoot = path.join(repoRoot, params.plan.archiveRoot);
-    const tempTargetRoot = path.join(repoRoot, '.aops', 'projects', `.tmp-${params.plan.projectSlug}-migrate-${path.basename(params.plan.archiveRoot)}`);
+    const tempTargetRoot = path.join(repoRoot, '.aops-cache', 'projects', `.tmp-${params.plan.projectSlug}-migrate-${path.basename(params.plan.archiveRoot)}`);
     const targetRoot = path.join(repoRoot, params.plan.localRoot);
     const sourceProjectman = path.join(repoRoot, '.aops', 'projectman');
     const sourceAgentspace = path.join(repoRoot, '.aops', 'agentspace');
@@ -1045,9 +1045,9 @@ export function makeProjectCommand() {
         await runProjectLink(options);
     });
     applyProjectContextOptions(cmd.command('migrate-local-root')
-        .description('Plan or apply flat .aops projectman/agentspace migration into .aops/projects/<slug>')
+        .description('Plan or apply flat .aops projectman/agentspace migration into .aops-cache/projects/<slug>')
         .requiredOption('--project-slug <slug>', 'Repo project slug to migrate')
-        .requiredOption('--local-root <path>', 'Target local root, normally .aops/projects/<slug>')
+        .requiredOption('--local-root <path>', 'Target local root, normally .aops-cache/projects/<slug>')
         .option('--dry-run', 'Build the migration summary without mutating files')
         .option('--apply', 'Apply the migration after dry-run review')
         .option('--confirm', 'Required with --apply because flat roots are moved to an archive')
@@ -1066,7 +1066,7 @@ export function makeProjectCommand() {
             'aops-cli project create --name "Demo Project" --apply --json',
             'aops-cli project update --id <project-id> --project-type app --apply --json',
             'aops-cli project link --slug aops-cockpit --mode hosted-only --apply --json',
-            'aops-cli project migrate-local-root --project-slug aops --local-root .aops/projects/aops --dry-run --json',
+            'aops-cli project migrate-local-root --project-slug aops --local-root .aops-cache/projects/aops --dry-run --json',
             'aops-cli project links list --json',
         ],
         guide: GUIDE_PATHS.agentspace,

package/dist/commands/prompt.js

@@ -1015,7 +1015,7 @@ export function makePromptCommand() {
         guide: GUIDE_PATHS.agentspace,
         notes: [
             'Canonical reusable prompt truth lives in aops-server/DB; create/update/publish through these prompt commands.',
-            '.aops/hosted/prompts/** is a read-only repo mirror refreshed by sync pull/bootstrap, not an authoring source.',
+            '.aops-cache/hosted/prompts/** is a read-only repo mirror refreshed by sync pull/bootstrap, not an authoring source.',
             'Prompt version list/inspect/current are curated read surfaces and do not require --apply; use --summary unless you need full prompt-version content.',
             'When --version is omitted, the CLI resolves the next version number from existing prompt versions.',
         ],

package/dist/commands/repo-sync.js

@@ -12,6 +12,7 @@ import { parseFrontmatterDocument, readLocalMemoryEntries, rebuildLocalMemoryWor
 import { readExperienceItems, rebuildExperienceWorkspace, } from '../utils/experience-workspace.js';
 import { resolveOwnerScopeIdFromProjectRecord, resolveProjectBindingContext, } from '../utils/project-context.js';
 import { collectRepoFirstSyncRecords, rebuildProjectmanViews, resolveRepoFirstAgentspacePaths, resolveRepoFirstProjectmanPaths, } from '../utils/repo-first-projectman.js';
+import { ensureAopsPrivatePathsIgnored, resolveAopsCacheRoot, resolveRepoFirstWorkspaceRelativeRoot } from '../utils/repo-first-storage.js';
 import { loadAopsRepoConfig, loadAopsRepoConfigReadOnly, readAopsRepoConfigReadOnly, } from '../utils/repo-config.js';
 import { hostedProjectKey, rebuildHostedWorkspace, syncHostedMirrorKind, } from '../utils/hosted-workspace.js';
 import { GUIDE_PATHS } from '../utils/guide-paths.js';
@@ -558,7 +559,7 @@ function emit(options, envelope, fallback) {
     console.log(JSON.stringify(envelope.result ?? envelope, null, 2));
 }
 async function writeState(repoRoot, payload) {
-    const statePath = path.join(repoRoot, '.aops', 'sync', 'state.json');
+    const statePath = path.join(resolveAopsCacheRoot(repoRoot), 'sync', 'state.json');
     await fs.mkdir(path.dirname(statePath), { recursive: true });
     const previous = await readState(repoRoot);
     await writeFileWithRetry(statePath, `${JSON.stringify({
@@ -570,7 +571,7 @@ async function writeState(repoRoot, payload) {
     return statePath;
 }
 async function readState(repoRoot) {
-    const statePath = path.join(repoRoot, '.aops', 'sync', 'state.json');
+    const statePath = path.join(resolveAopsCacheRoot(repoRoot), 'sync', 'state.json');
     try {
         const parsed = JSON.parse(await fs.readFile(statePath, 'utf8'));
         return isRecord(parsed) ? parsed : {};
@@ -580,19 +581,7 @@ async function readState(repoRoot) {
     }
 }
 async function ensureGitignore(repoRoot) {
-    const gitignorePath = path.join(repoRoot, '.gitignore');
-    const entry = '.aops/sync/state.json';
-    let content = '';
-    try {
-        content = await fs.readFile(gitignorePath, 'utf8');
-    }
-    catch {
-        content = '';
-    }
-    if (content.split(/\r?\n/).includes(entry))
-        return;
-    const next = `${content.trimEnd()}${content.trimEnd() ? '\n' : ''}${entry}\n`;
-    await writeFileWithRetry(gitignorePath, next, 'utf8');
+    await ensureAopsPrivatePathsIgnored(repoRoot);
 }
 function commonFrontmatter(params) {
     const now = new Date().toISOString();
@@ -613,6 +602,70 @@ function commonFrontmatter(params) {
         storage: 'local-cache',
     });
 }
+function markdownHeading(value, fallback) {
+    return normalizeNonEmpty(value)?.replace(/\s+/g, ' ') ?? fallback;
+}
+function progressLabel(value) {
+    if (!isRecord(value))
+        return undefined;
+    const completed = numberField(value.completed);
+    const actionable = numberField(value.actionable);
+    const total = numberField(value.total);
+    const ratio = typeof value.ratio === 'number' && Number.isFinite(value.ratio)
+        ? `${Math.round(value.ratio * 100)}%`
+        : undefined;
+    const count = completed !== undefined && (actionable ?? total) !== undefined
+        ? `${completed}/${actionable ?? total}`
+        : undefined;
+    if (count && ratio)
+        return `${count} (${ratio})`;
+    return count ?? ratio;
+}
+export function renderSprintMirrorBody(sprint) {
+    const lines = [`# ${markdownHeading(sprint.name ?? sprint.title, 'Untitled sprint')}`, '', '## Phases'];
+    const phases = toRecordArray(sprint.phases);
+    if (phases.length === 0) {
+        lines.push('', '_No phases._');
+        return `${lines.join('\n')}\n`;
+    }
+    phases.forEach((phase, phaseIndex) => {
+        lines.push('', `### ${phaseIndex + 1}. ${markdownHeading(phase.name, `Phase ${phaseIndex + 1}`)}`);
+        const phaseMeta = [
+            ['ID', normalizeNonEmpty(phase.id)],
+            ['Status', normalizeNonEmpty(phase.status)],
+            ['Progress', progressLabel(phase.progress)],
+        ];
+        for (const [label, value] of phaseMeta) {
+            if (value)
+                lines.push(`- ${label}: ${value}`);
+        }
+        const description = normalizeNonEmpty(phase.description);
+        if (description)
+            lines.push('', description);
+        lines.push('', '#### Microtasks');
+        const microtasks = toRecordArray(phase.microtasks);
+        if (microtasks.length === 0) {
+            lines.push('', '_No microtasks._');
+            return;
+        }
+        microtasks.forEach((microtask, microtaskIndex) => {
+            lines.push('', `##### ${microtaskIndex + 1}. ${markdownHeading(microtask.title, `Microtask ${microtaskIndex + 1}`)}`);
+            const microtaskMeta = [
+                ['ID', normalizeNonEmpty(microtask.id)],
+                ['Status', normalizeNonEmpty(microtask.status)],
+                ['Position', numberField(microtask.position)?.toString()],
+            ];
+            for (const [label, value] of microtaskMeta) {
+                if (value)
+                    lines.push(`- ${label}: ${value}`);
+            }
+            const notes = normalizeNonEmpty(microtask.notes);
+            if (notes)
+                lines.push('', '**Notes**', '', notes);
+        });
+    });
+    return `${lines.join('\n')}\n`;
+}
 async function writeProjectmanSeedFile(params) {
     const remoteId = normalizeNonEmpty(params.remote.id);
     const existing = remoteId ? await findRecordByRemoteId(params.dir, remoteId) : null;
@@ -622,7 +675,12 @@ async function writeProjectmanSeedFile(params) {
     const localId = normalizeNonEmpty(existing?.frontmatter.localId) ?? randomUUID();
     const title = normalizeNonEmpty(params.remote[params.titleKey]) ?? normalizeNonEmpty(params.remote.name) ?? normalizeNonEmpty(params.remote.title) ?? localId;
     const filePath = existing?.filePath ?? path.join(params.dir, `${slugify(title)}-${localId.slice(0, 8)}.md`);
-    const body = `# ${title}\n`;
+    const body = params.entityType === 'projectman.sprint'
+        ? renderSprintMirrorBody(params.remote)
+        : `# ${title}\n`;
+    const remoteFrontmatter = params.entityType === 'projectman.sprint'
+        ? Object.fromEntries(Object.entries(params.remote).filter(([key]) => key !== 'phases'))
+        : params.remote;
     const frontmatter = withBaseHash({
         ...commonFrontmatter({
             entityType: params.entityType,
@@ -632,7 +690,7 @@ async function writeProjectmanSeedFile(params) {
             remoteId,
             remoteUpdatedAt: normalizeNonEmpty(params.remote.updatedAt),
         }),
-        ...params.remote,
+        ...remoteFrontmatter,
         id: localId,
         localId,
         remoteId,
@@ -707,6 +765,7 @@ async function writeUtaskSeedFile(params) {
         phaseId: normalizeNonEmpty(params.phase.localId) ?? normalizeNonEmpty(params.phase.id),
         phaseRemoteId: normalizeNonEmpty(params.phase.remoteId) ?? normalizeNonEmpty(params.phase.id),
         phaseName: normalizeNonEmpty(params.phase.name),
+        phasePosition: numberField(params.phase.position),
         title,
         status: normalizeNonEmpty(params.microtask.status) ?? 'todo',
         position: numberField(params.microtask.position),
@@ -1210,7 +1269,11 @@ async function collectSyncPullData(options, command, context, apiState) {
             filesWritten.push(...await writeUtaskSeedFilesFromSprint({
                 repoRoot: context.repoRoot,
                 localRoot: context.localRoot,
-                sprint: sprintRecord.frontmatter,
+                sprint: {
+                    ...row,
+                    ...sprintRecord.frontmatter,
+                    phases: row.phases,
+                },
                 projectId,
                 scopeId,
                 idsAreRemote: true,
@@ -1790,6 +1853,7 @@ async function runSyncRebuildViews(options) {
             items: memoryItems,
         });
         await rebuildHostedWorkspace(context.repoRoot);
+        const workspaceRoot = resolveRepoFirstWorkspaceRelativeRoot(context);
         emit(options, {
             command: 'sync.rebuild-views',
             surface: 'hosted-cache-sync',
@@ -1798,10 +1862,10 @@ async function runSyncRebuildViews(options) {
                 ok: true,
                 data: {
                     views: [
-                        '.aops/projectman/views/index.md',
-                        '.aops/agentspace/experience/index.md',
-                        '.aops/agentspace/memory/index.md',
-                        '.aops/hosted/index.md',
+                        `${workspaceRoot}/projectman/views/index.md`,
+                        `${workspaceRoot}/agentspace/experience/index.md`,
+                        `${workspaceRoot}/agentspace/memory/index.md`,
+                        '.aops-cache/hosted/index.md',
                     ],
                 },
             },
@@ -1886,13 +1950,14 @@ export function makeSyncCommand() {
             'aops-cli sync pull --apply --json',
             'aops-cli sync pull --all-projects --apply --json',
             'aops-cli sync pull --apply --hosted-project-slug aops --json',
-            'aops-cli sync resolve --path .aops/projectman/sprints/demo.md --prefer remote --json',
+            'aops-cli sync resolve --path .aops-cache/projectman/sprints/demo.md --prefer remote --json',
         ],
         guide: GUIDE_PATHS.operator,
         notes: [
-            'Server-first: hosted server state is the single source of truth. `.aops/**` source files are a read-only local cache refreshed by `sync pull`/`sync bootstrap`; there is no `sync push` (write to hosted state with the hosted CLI/domain ops).',
-            'Hosted reusable prompts/skills stay single-source on the server; sync pull/bootstrap only mirror them into `.aops/hosted/**` as read-only local context.',
-            'Hosted Docman documents and guide mirrors use `aops-cli doc mirror pull --out-dir ./.aops/docman`; `sync pull` does not refresh `.aops/docman/**`.',
+            'Server-first: hosted server state is the single source of truth. `.aops-cache/**` files are a generated read-only local cache refreshed by `sync pull`/`sync bootstrap`; there is no `sync push` (write to hosted state with the hosted CLI/domain ops).',
+            '`.aops/aops.config.json` is private repo metadata; both `/.aops/` and `/.aops-cache/` are ignored so public repositories do not publish operator state.',
+            'Hosted reusable prompts/skills stay single-source on the server; sync pull/bootstrap only mirror them into `.aops-cache/hosted/**` as read-only local context.',
+            'Hosted Docman documents and guide mirrors use `aops-cli doc mirror pull --out-dir ./.aops-cache/docman`; `sync pull` does not refresh `.aops-cache/docman/**`.',
             '`sync status` and `sync diff` accept repeatable selective scope flags: --board, --task, --sprint, --issue, --feedback, --review-request, and --record.',
             'Board/task/sprint selection expands to related Projectman records and linked Agentspace memory/experience context. `--record` matches local path, localId, remoteId, slug, name, or title.',
             '`--all-projects` runs status/diff/pull/bootstrap once per repo-config project (server-first; no authoring-mode split), skips only projects without a localRoot in a multi-project repo, and reports project-level errors without fail-fast.',
@@ -1900,7 +1965,7 @@ export function makeSyncCommand() {
             'Hosted writes are the source of truth, so the local cache never replays back. If a cache file drifts, re-run `sync pull` to refresh it from the server; `sync resolve --prefer remote` re-adopts a single record from hosted state.',
             'Browser/cockpit surfaces must never assume the remote aops-server machine has the repo. Use `aops-cli sync sidecar --allow-origin <cockpit-origin>` on the client machine to expose a localhost-only read-only status/diff bridge.',
             '`localId` is UUIDv4. `remoteId` is filled after hosted sync/bootstrap.',
-            '.aops/sync/state.json is local machine sync state and is ignored by git.',
+            '.aops-cache/sync/state.json is local machine sync state and is ignored by git.',
         ],
     }));
     return cmd;