document360-writer 0.4.65 → 0.4.67

package/dist/commands/catchup.d.ts

@@ -0,0 +1,22 @@
+import type { ReplContext } from '../repl.js';
+import type { SlashCommandResult } from './index.js';
+export type PendingSummary = {
+    hints: number;
+    requests: number;
+    answers: number;
+};
+/** Deterministic local counts of queued work (hints + builder messages). Drift is network and is
+    checked by the agent via d360_sync_status inside the prompt, not here. */
+export declare function pendingSummary(cwd: string): PendingSummary;
+/** A short human phrase for a pending summary, or null when nothing local is queued. */
+export declare function pendingLine(s: PendingSummary): string | null;
+export declare function parseCatchUpArgs(args: string[]): {
+    publish: boolean;
+};
+/** The consolidated staged prompt: trust → gather → decide → estimate/gate → write → close-loop → push. */
+export declare function buildCatchUpPrompt({ publish }: {
+    publish: boolean;
+}): string;
+/** Classic-REPL `/catch-up`. Always forwards (it's the double-check) — even with no local queue it still
+    runs the sync/gap check to catch code changes the builder didn't hint. */
+export declare function catchupCommand(args: string[], ctx?: ReplContext): Promise<SlashCommandResult>;

package/dist/commands/devhints.d.ts

@@ -1,7 +1,16 @@
 import type { SlashCommandResult } from './index.js';
 import type { ReplContext } from '../repl.js';
-/** Bump when the guide content changes — lets a future check detect a stale committed guide. */
-export declare const DEV_HINTS_GUIDE_VERSION = 2;
+/**
+ * The version of the WHOLE devhints script — the committed guide AND the copy-run prompt, which evolve
+ * as one unit. Bump on any change to either. Embedded in the guide header, the run prompt, and the
+ * on-disk handshake trace (devhints-state.json) so a future change is detectable: when the code version
+ * is ahead of what the builder last completed, /devhints + /doctor tell the user to re-paste.
+ *   v1 → original one-way hints. v2 → re-run-safe single-prompt onboarding.
+ *   v3 → two-way messages (Part 3) + on-demand hand-off (Part 4) + version trace.
+ *   v4 → the writer can send the builder a `request` (not just a question), e.g. an auto "re-run
+ *        onboarding" note when this protocol version moves ahead of what the builder last completed.
+ */
+export declare const DEVHINTS_VERSION = 4;
 /**
  * The committed protocol guide the SOURCE repo's coding agent follows. Self-contained because that
  * agent has none of d360-writer's context. Two parts: (1) a ONE-TIME architecture brief that onboards
@@ -33,8 +42,48 @@ export declare function devhintsCommand(_args: string[], ctx: ReplContext): Prom
  * was a first-time setup or a refresh.
  */
 export declare function devHintsRunPrompt(): string;
+/** The devhints handshake trace (`.d360-writer/devhints-state.json`). `emitted*` = what d360-writer
+    last handed the builder; `completed*` = what the builder's agent last ran (stamped by the run prompt,
+    step 6). The gap between completedVersion and DEVHINTS_VERSION is what staleness detection reads. */
+export type DevhintsState = {
+    emittedVersion?: number;
+    emittedAt?: string;
+    completedVersion?: number;
+    completedAt?: string;
+    completedCommit?: string;
+};
+/** Read the handshake trace; null if absent or unparseable (treated as "never set up"). */
+export declare function readDevhintsState(cwd: string): DevhintsState | null;
+/** Record that /devhints just emitted the current version, preserving the builder's completion fields. */
+export declare function writeDevhintsEmitted(cwd: string, now: string): void;
+export type DevhintsStaleness = {
+    status: 'unset' | 'stale' | 'current';
+    completedVersion?: number;
+};
+/** Compare what the builder completed against the current script version. `unset` = the builder hasn't
+    run the hand-off (no completion stamp); `stale` = ran an older version; `current` = up to date. */
+export declare function devhintsStaleness(cwd: string): DevhintsStaleness;
+/** Subject prefix that marks the auto "re-run onboarding" request, so we never queue a duplicate. */
+export declare const ONBOARDING_REQUEST_MARKER = "Re-run dev\u2194docs onboarding (protocol v";
+export type DevhintsReconcileResult = {
+    guideRefreshed: boolean;
+    notifiedBuilder: boolean;
+    toVersion: number;
+    completedVersion?: number;
+};
+/**
+ * Keep the dev↔docs onboarding protocol self-healing, with no human re-paste. Runs at launch when a
+ * guide already exists (devhints is in use):
+ *  - if the package's DEVHINTS_VERSION is ahead of what we last EMITTED → rewrite the committed guide +
+ *    re-stamp `emitted` (the new protocol lands on disk on its own);
+ *  - if it's ahead of what the builder COMPLETED → leave ONE `from: docs, kind: request` message in the
+ *    mailbox with the run prompt embedded (idempotent: skip if an open onboarding request already exists),
+ *    so the builder re-onboards on their next session.
+ * Pure file ops, never throws; returns what it did so the wrapper can surface a one-line note.
+ */
+export declare function reconcileDevhints(cwd: string, now?: string): DevhintsReconcileResult;
 /**
  * The `/devhints` screen: confirms what was scaffolded, then shows the single copy-run prompt
  * (devHintsRunPrompt) and the closing "come back and run" guidance. One prompt, zero manual file edits.
  */
-export declare function renderDevHintsHandoff(): string[];
+export declare function renderDevHintsHandoff(stale?: DevhintsStaleness): string[];

package/dist/commands/document.d.ts

@@ -0,0 +1,19 @@
+import type { ReplContext } from '../repl.js';
+import type { SlashCommandResult } from './index.js';
+/** Open `request` messages (the builder's explicit "please document X") awaiting the docs agent. */
+export declare function openRequestCount(cwd: string): number;
+/** Split `--publish` off the args; the rest is the free-text description of what changed. */
+export declare function parseDocumentArgs(args: string[]): {
+    publish: boolean;
+    what: string;
+};
+/** The prompt driving the document-handoff skill. `what` is the builder's description (empty → act on
+    the open request messages in the inbox). `publish` appends a draft-then-publish instruction. */
+export declare function buildDocumentPrompt(what: string, publish?: boolean): string;
+declare const NO_REQUESTS_HINT = "Nothing to document yet. Say what changed: /document <what you shipped> \u2014 or have the builder drop a request via their /devhints hand-off.";
+/**
+ * Classic-REPL `/document`: with text → document it; bare with open requests → process them; bare with
+ * nothing → tell the user how to describe the work.
+ */
+export declare function documentCommand(args: string[], ctx?: ReplContext): Promise<SlashCommandResult>;
+export { NO_REQUESTS_HINT };

package/dist/commands/inbox.d.ts

@@ -0,0 +1,11 @@
+import type { ReplContext } from '../repl.js';
+import type { SlashCommandResult } from './index.js';
+/** Count of open builder messages addressed to the docs agent — drives the ambient nudge + bare /inbox. */
+export declare function openForDocsCount(cwd: string): number;
+/** The prompt that drives inbox processing. Generic over the action so it composes with the
+    document-handoff skill (Phase B) for requests and gap-analysis's update logic for answers. */
+export declare function buildInboxPrompt(): string;
+/**
+ * Classic-REPL `/inbox`: if there are open messages, forward the processing prompt; otherwise say so.
+ */
+export declare function inboxCommand(_args: string[], ctx?: ReplContext): Promise<SlashCommandResult>;

package/dist/commands/reset.d.ts

@@ -20,9 +20,10 @@ export declare function performReset(cwd: string, targets: string[]): {
         error: string;
     }[];
 };
-/** Count UNcommitted (untracked or modified) files under .d360-writer/hints/ — they'd be lost by a
-    reset with no git copy to restore. Read-only git call; 0 on any error (no git, etc.). */
+/** Uncommitted doc hints (`.d360-writer/hints/`) that a reset would destroy. */
 export declare function uncommittedHintCount(cwd: string): number;
+/** Uncommitted two-way messages (`.d360-writer/messages/`) that a reset would destroy. */
+export declare function uncommittedMessageCount(cwd: string): number;
 /** The destructive preview shown before the typed-name confirmation. */
 export declare function resetPreviewLines(cwd: string, targets: string[]): string[];
 /** `/reset` [DANGER] — classic REPL: preview → typed-name confirmation → delete. */

package/dist/commands/update.d.ts

@@ -0,0 +1,11 @@
+import type { SlashCommandResult } from './index.js';
+export declare const SELF_UPDATE_PKG = "document360-writer";
+export declare const SELF_UPDATE_HINT = "npm i -g document360-writer@latest";
+/** Run the global install. Best-effort: resolves {ok,output}, never throws. Windows resolves npm.cmd
+    via shell:true. */
+export declare function runSelfUpdate(): Promise<{
+    ok: boolean;
+    output: string;
+}>;
+/** Classic-REPL `/update`: install, then tell the user to relaunch. */
+export declare function updateCommand(): Promise<SlashCommandResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document360-writer",
-  "version": "0.4.65",
+  "version": "0.4.67",
   "description": "Standalone documentation agent CLI. Reads your code, writes your docs. Specialized for Document360 publishing.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "@inquirer/prompts": "^8.4.3",
     "commander": "^14.0.3",
     "diff": "^8.0.4",
-    "document360-engine": "^0.2.37",
+    "document360-engine": "^0.2.39",
     "ink": "^5.2.1",
     "picocolors": "^1.1.1",
     "react": "^18.3.1",