briefops 1.0.0

package/dist/schemas/patch.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export declare const skillPatchStatuses: readonly ["proposed", "applied", "rejected"];
+export declare const skillPatchSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    skill: z.ZodString;
+    from_log: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<["proposed", "applied", "rejected"]>>;
+    target_section: z.ZodDefault<z.ZodString>;
+    lessons: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    additions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    applied_at: z.ZodOptional<z.ZodString>;
+    rejected_at: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    lessons: string[];
+    id: string;
+    created_at: string;
+    skill: string;
+    status: "proposed" | "applied" | "rejected";
+    from_log: string;
+    target_section: string;
+    additions: string[];
+    applied_at?: string | undefined;
+    rejected_at?: string | undefined;
+}, {
+    id: string;
+    created_at: string;
+    skill: string;
+    from_log: string;
+    lessons?: string[] | undefined;
+    status?: "proposed" | "applied" | "rejected" | undefined;
+    applied_at?: string | undefined;
+    rejected_at?: string | undefined;
+    target_section?: string | undefined;
+    additions?: string[] | undefined;
+}>;
+export type SkillPatch = z.infer<typeof skillPatchSchema>;
+export type SkillPatchStatus = (typeof skillPatchStatuses)[number];

package/dist/schemas/patch.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export const skillPatchStatuses = ["proposed", "applied", "rejected"];
+export const skillPatchSchema = z.object({
+    id: z.string().min(1),
+    created_at: z.string().datetime(),
+    skill: z.string().min(1),
+    from_log: z.string().min(1),
+    status: z.enum(skillPatchStatuses).default("proposed"),
+    target_section: z.string().default("Check"),
+    lessons: z.array(z.string()).default([]),
+    additions: z.array(z.string()).default([]),
+    applied_at: z.string().datetime().optional(),
+    rejected_at: z.string().datetime().optional()
+});
+//# sourceMappingURL=patch.js.map

package/dist/schemas/patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.js","sourceRoot":"","sources":["../../src/schemas/patch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAE/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACtD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC"}

package/dist/schemas/project.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const projectFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    max_tokens: z.ZodDefault<z.ZodNumber>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    tags: string[];
+    description: string;
+    max_tokens: number;
+}, {
+    name: string;
+    tags?: string[] | undefined;
+    description?: string | undefined;
+    max_tokens?: number | undefined;
+}>;
+export type ProjectFrontmatter = z.infer<typeof projectFrontmatterSchema>;
+export type ProjectDocument = {
+    data: ProjectFrontmatter;
+    body: string;
+    raw: string;
+};

package/dist/schemas/project.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export const projectFrontmatterSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().default(""),
+    max_tokens: z.number().int().positive().default(500),
+    tags: z.array(z.string()).default([])
+});
+//# sourceMappingURL=project.js.map

package/dist/schemas/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/schemas/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACpD,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACtC,CAAC,CAAC"}

package/dist/schemas/skill.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const skillFrontmatterSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodDefault<z.ZodString>;
+    description: z.ZodDefault<z.ZodString>;
+    max_tokens: z.ZodDefault<z.ZodNumber>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    tags: string[];
+    version: string;
+    description: string;
+    max_tokens: number;
+}, {
+    name: string;
+    tags?: string[] | undefined;
+    version?: string | undefined;
+    description?: string | undefined;
+    max_tokens?: number | undefined;
+}>;
+export type SkillFrontmatter = z.infer<typeof skillFrontmatterSchema>;
+export type SkillDocument = {
+    data: SkillFrontmatter;
+    body: string;
+    raw: string;
+};

package/dist/schemas/skill.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export const skillFrontmatterSchema = z.object({
+    name: z.string().min(1),
+    version: z.string().default("0.1.0"),
+    description: z.string().default(""),
+    max_tokens: z.number().int().positive().default(700),
+    tags: z.array(z.string()).default([])
+});
+//# sourceMappingURL=skill.js.map

package/dist/schemas/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/schemas/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;IACpC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACpD,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACtC,CAAC,CAAC"}

package/dist/schemas/worker.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const workerStatuses: readonly ["active", "draft", "archived"];
+export declare const workerProfileSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+    default_skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    style: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    max_tokens: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodDefault<z.ZodEnum<["active", "draft", "archived"]>>;
+}, "strip", z.ZodTypeAny, {
+    status: "active" | "archived" | "draft";
+    name: string;
+    description: string;
+    max_tokens: number;
+    default_skills: string[];
+    style: string[];
+    project?: string | undefined;
+}, {
+    name: string;
+    project?: string | undefined;
+    status?: "active" | "archived" | "draft" | undefined;
+    description?: string | undefined;
+    max_tokens?: number | undefined;
+    default_skills?: string[] | undefined;
+    style?: string[] | undefined;
+}>;
+export type WorkerProfile = z.infer<typeof workerProfileSchema>;
+export type WorkerStatus = (typeof workerStatuses)[number];

package/dist/schemas/worker.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export const workerStatuses = ["active", "draft", "archived"];
+export const workerProfileSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().default(""),
+    project: z.string().optional(),
+    default_skills: z.array(z.string()).default([]),
+    style: z.array(z.string()).default([]),
+    max_tokens: z.number().int().positive().default(300),
+    status: z.enum(workerStatuses).default("active")
+});
+//# sourceMappingURL=worker.js.map

package/dist/schemas/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/schemas/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAU,CAAC;AAEvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACpD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;CACjD,CAAC,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const briefopsVersion = "1.0.0";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Keep this version in sync with package.json.
+export const briefopsVersion = "1.0.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC"}

package/docs/codex-resume.md

@@ -0,0 +1,13 @@
+# Codex Resume
+
+`briefops codex resume` combines a handoff brief with a Codex execution contract.
+
+```bash
+briefops codex resume --worker quant-reviewer --task "Continue the rebalance review and identify remaining risks." --save
+```
+
+Use `--export-policy shared-only` when the resume prompt may be pasted outside the local Codex workspace.
+
+Shared-only resume output includes selected shared/exportable memory and omits private memory, local project file details, raw work logs, open risks, local next steps, private worker history, and private metadata counts.
+
+The generated prompt includes continuity rules, evidence gates, a completion signal, and after-completion logging instructions.

package/docs/compatibility.md

@@ -0,0 +1,49 @@
+# BriefOps 1.0 Compatibility Policy
+
+BriefOps follows semantic versioning for the public CLI and local file formats.
+
+## Stable In 1.0
+
+- Public commands documented in `README.md`.
+- `.briefops/` source file formats documented in `docs/file-format.md`.
+- `shared-only` and `local-private` export policy names.
+- Human-approved memory proposal and skill patch flow.
+- Workspace lock behavior for local write operations.
+- Harness router export targets: `agents-md`, `claude-md`, `cursor-rules`, and `all`.
+
+## Compatible Changes
+
+Minor and patch releases may:
+
+- Add optional fields with safe defaults.
+- Add new commands or flags.
+- Add new generated artifact sections.
+- Improve deterministic selection, trimming, and warnings.
+- Add new doctor checks that warn without rewriting user data.
+
+## Breaking Changes
+
+Breaking changes require a new major version. Examples:
+
+- Removing or renaming stable CLI commands or flags.
+- Changing required fields in documented `.briefops/` source formats.
+- Changing `shared-only` so it includes private local content or private metadata counts.
+- Auto-applying memory proposals or skill patches.
+- Requiring a hosted service, network dependency, agent runtime, MCP server, vector database, or cloud sync.
+
+## Workspace Version Support
+
+New 1.0 workspaces write `version: 1.0.0` in `.briefops/config.yaml`.
+
+BriefOps 1.0 can read legacy `0.x` workspace configs on a best-effort compatibility basis. Future `2.x` workspace configs fail with an explicit upgrade error instead of silently reading incompatible data.
+
+## Migration Policy
+
+BriefOps does not rewrite workspace data during normal reads. Commands that mutate user data are explicit, local, file-backed, and protected by workspace locks.
+
+If a future release needs a migration, it must provide:
+
+- a documented command or manual procedure,
+- dry-run or inspection guidance,
+- no automatic approval of memory or skill patches,
+- tests covering old fixtures.

package/docs/concept.md

@@ -0,0 +1,13 @@
+# BriefOps Concept
+
+BriefOps is a local-first, token-aware persistent work history layer for AI coding agents.
+
+It does not run Codex, Claude Code, or other agents. It prepares compact continuity artifacts so a fresh thread can start with the usable parts of prior work: project constraints, worker style, active decisions, lessons, incidents, and recent logs.
+
+The core loop is:
+
+```text
+brief -> work -> log -> proposal -> approved memory -> worker summary -> handoff/resume
+```
+
+Raw logs remain audit records. Memory is curated operational knowledge that requires human approval.

package/docs/evals.md

@@ -0,0 +1,18 @@
+# Evals
+
+BriefOps evals are deterministic checklist cases for generated artifacts.
+
+Use them to verify that important context appears in generated briefs:
+
+```bash
+briefops eval create continuity-rebalance --worker quant-reviewer --input "Continue rebalance review" --expected "turnover warning threshold"
+briefops eval run --worker quant-reviewer
+```
+
+Continuity evals should check for prior lessons, decisions, and sections that a fresh thread needs before acting.
+
+Prime-context evals should also check that the compact output is materially smaller than a manual history dump:
+
+```bash
+npm test -- tests/prime.test.ts
+```

package/docs/file-format.md

@@ -0,0 +1,67 @@
+# BriefOps File Format Contract
+
+BriefOps stores all user data under `.briefops/`. Version 1.0 treats these files as the durable local data contract.
+
+## Workspace
+
+- `.briefops/config.yaml`
+  - `version`: workspace schema version. New 1.0 workspaces use `1.0.0`.
+  - `created_at`: ISO datetime.
+  - `defaults.project`: optional default project name.
+  - `defaults.worker`: optional default worker name.
+  - `token_budgets.prime`: default prime budget.
+  - `token_budgets.resume`: default resume/pack budget.
+  - `memory_categories`: supported memory categories.
+
+## Source Files
+
+- `.briefops/projects/<name>.project.md`
+  - Markdown with YAML frontmatter.
+  - Stable frontmatter: `name`, `description`, `max_tokens`, `tags`.
+  - Body is local project context. Shared-only exports omit it.
+
+- `.briefops/skills/<name>.skill.md`
+  - Markdown with YAML frontmatter.
+  - Stable frontmatter: `name`, `version`, `description`, `max_tokens`, `tags`.
+  - Skill patches append checklist items and changelog entries only after approval.
+
+- `.briefops/workers/<name>.worker.yaml`
+  - Stable fields: `name`, `description`, `project`, `default_skills`, `style`, `max_tokens`, `status`.
+
+## Memory And Logs
+
+- `.briefops/memory/<category>.yaml`
+  - Shape: `items: MemoryItem[]`.
+  - Stable item fields: `id`, `type`, `status`, `project`, `skill`, `content`, `source`, `created_at`, `tags`, `visibility`, `exportable`.
+  - Supported statuses: `active`, `stale`, `deprecated`, `superseded`, `archived`.
+  - Supported visibility values: `private`, `shared`, `public`.
+
+- `.briefops/logs/*.yaml`
+  - Stable fields: `id`, `created_at`, `project`, `skill`, `worker`, `task`, `result`, `lessons`, `open_risks`, `next_steps`, `decisions`, `incidents`, `files_changed`, `commands_run`, `notes`.
+  - Logs are private local history. Shared-only exports omit raw logs.
+
+## Review Queues
+
+- `.briefops/memory-proposals/*.memory-proposal.yaml`
+  - Stable fields: `id`, `created_at`, `from_log`, `status`, `project`, `skill`, `worker`, `items`, `applied_at`, `rejected_at`.
+  - Legacy `proposals` arrays remain readable and are normalized to `items`.
+  - Proposal entries use memory item fields plus `category` and `rationale`.
+
+- `.briefops/patches/*.patch.yaml`
+  - Stable fields: `id`, `created_at`, `skill`, `from_log`, `status`, `target_section`, `lessons`, `additions`, `applied_at`, `rejected_at`.
+
+## Generated Artifacts
+
+- `.briefops/handoffs/*.md`
+- `.briefops/codex/prompts/*.md`
+- `.briefops/briefs/*.md`
+
+Generated artifacts are reproducible outputs, not the canonical data store. Their command names, privacy behavior, and frontmatter metadata are stable in 1.0, but users should keep durable facts in source files, memory, logs, proposals, and patches.
+
+## Harness Router Files
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.cursor/rules/briefops-*.mdc`
+
+`briefops export` generates router files. They contain command routing and safety boundaries only. They must not copy raw memory, logs, worker summaries, handoffs, incidents, or private decisions.

package/docs/handoff-briefs.md

@@ -0,0 +1,9 @@
+# Handoff Briefs
+
+Handoff briefs prepare a fresh AI coding thread to continue without restarting from zero.
+
+```bash
+briefops handoff generate --worker quant-reviewer --task "Continue rebalance review" --adapter codex --save
+```
+
+A handoff includes project context, worker summary, recent work, active decisions, lessons, incidents, deprecated notes when relevant, a recommended start, after-completion commands, and token accounting.

package/docs/integrations/harnesses.md

@@ -0,0 +1,74 @@
+# Harness Integrations
+
+BriefOps is not an agent harness. It does not run models, manage subscriptions, install hooks, expose MCP tools, or route work across agents.
+
+BriefOps is a local memory and context ledger that a harness can read before work and update after work.
+
+## Recommended Pattern
+
+Before a task:
+
+```bash
+briefops prime --task "<task>" --format codex --max-tokens 800
+```
+
+After meaningful work:
+
+```bash
+briefops finish --worker <worker> --task "<task>" --result "<result>"
+briefops memory proposal-show latest
+briefops approve latest
+```
+
+For a fresh thread:
+
+```bash
+briefops continue --worker <worker> --task "<next task>" --pack
+```
+
+For portable or shared context:
+
+```bash
+briefops prime --task "<task>" --format codex --export-policy shared-only
+briefops pack resume --worker <worker> --task "<task>" --export-policy shared-only
+```
+
+To generate always-visible harness router files:
+
+```bash
+briefops export agents-md
+briefops export claude-md
+briefops export cursor-rules
+briefops export all
+```
+
+These files should stay compact. They teach harnesses how to call BriefOps and do not copy private memory, raw logs, handoffs, or worker summaries.
+
+## LazyCodex / OmO
+
+Use LazyCodex or OmO for orchestration, hooks, LSP/MCP, and autonomous execution. Use BriefOps for durable local continuity.
+
+Suggested human workflow:
+
+```bash
+briefops prime --task "Implement the next scoped change." --format codex --max-tokens 800
+codex "Use the BriefOps prime context, then run ultrawork for this task."
+briefops finish --worker <worker> --task "Implement the next scoped change." --result "<verified result>"
+briefops memory proposal-show latest
+```
+
+Do not let a harness auto-run `briefops approve latest`. Approval should remain human-confirmed.
+
+## Codex App And Codex CLI
+
+Use `briefops codex plugin install` to generate local plugin assets under `.briefops/codex/plugin/briefops`.
+
+This command does not write to global Codex folders by default.
+
+## Claude Code
+
+BriefOps can coexist with `CLAUDE.md`. Keep `CLAUDE.md` for always-loaded project instructions and use BriefOps for task history, approved memory, handoffs, and shared-only packs.
+
+## Cursor
+
+BriefOps can coexist with Cursor rules and memories. Keep Cursor rules for editor behavior and use BriefOps for auditable cross-thread work history.

package/docs/memory-lifecycle.md

@@ -0,0 +1,23 @@
+# Memory Lifecycle
+
+BriefOps separates raw logs from durable memory.
+
+Allowed flow:
+
+```text
+log -> memory proposal -> human approval -> memory
+```
+
+Commands:
+
+```bash
+briefops memory propose-from-log latest
+briefops memory proposal-list
+briefops memory proposal-show <proposal-id>
+briefops memory proposal-apply <proposal-id>
+briefops memory proposal-reject <proposal-id>
+```
+
+Extraction is deterministic and local. Lessons become lesson memory. Notes prefixed with `decision:` or `fact:` become matching memory candidates. Results containing risk or failure language become incident candidates.
+
+Proposal generation and approval are local file-backed operations protected by workspace locks. BriefOps never auto-approves memory or skill patches.

package/docs/persistent-worker.md

@@ -0,0 +1,15 @@
+# Persistent Worker
+
+A BriefOps worker is not roleplay. It is a durable bundle of:
+
+- default project
+- default skills
+- style constraints
+- recent work history
+- active lessons
+- known failure patterns
+- judgment rules
+
+Use `briefops worker refresh-summary <worker>` to compile this into `.briefops/workers/summaries/<worker>.summary.md`.
+
+Handoffs and Codex resume prompts prefer this summary when it exists, so fresh threads inherit worker intelligence without dumping every prior log.

package/docs/privacy-model.md

@@ -0,0 +1,40 @@
+# BriefOps Privacy Model
+
+BriefOps is local-first. It stores work history, memory, proposals, patches, generated prompts, and plugin assets under `.briefops/` in the current repository.
+
+## Export Policies
+
+`local-private` is for local terminal and local Codex/Claude/Cursor use. It may include private project details, approved private memory, local work logs, risks, next steps, worker history, and metadata counts.
+
+`shared-only` is for artifacts that may leave the local workspace. It includes only memory items marked `visibility: shared` and `exportable: true`.
+
+Shared-only omits:
+
+- private memory,
+- local project file details,
+- raw work logs,
+- open risks,
+- local next steps,
+- private worker lessons,
+- private incidents,
+- recent work history,
+- private worker history,
+- private metadata counts.
+
+## Router Exports
+
+`briefops export agents-md`, `briefops export claude-md`, `briefops export cursor-rules`, and `briefops export all` generate router files. Router files point AI harnesses to BriefOps commands. They do not copy `.briefops` memory, logs, worker summaries, handoffs, incidents, or private decisions.
+
+## Human Approval
+
+BriefOps never auto-approves memory proposals or skill patches. Approval is always an explicit user action through `briefops approve`, `briefops memory proposal-apply`, or `briefops skill apply-patch`.
+
+## Doctor Checks
+
+`briefops doctor --privacy` checks local memory sharing hazards:
+
+- `.briefops/` gitignore coverage,
+- private memory marked exportable,
+- secret-like local memory strings.
+
+`briefops doctor --security --fix-stale-locks` removes stale lock files only. It does not remove fresh locks or other workspace files.

package/docs/quickstart.md

@@ -0,0 +1,74 @@
+# Quickstart
+
+## Codex First Context Path
+
+```bash
+briefops init
+briefops codex install
+briefops codex plugin install
+briefops skill create risk-review --description "Review risk and governance."
+briefops project create atlas-q --description "Rule-based quantitative system."
+briefops worker create quant-reviewer --project atlas-q --skills "risk-review" --style "skeptical,verify before completion"
+briefops worker use quant-reviewer
+briefops export all --worker quant-reviewer --force
+briefops memory add --type lessons --project atlas-q --skill risk-review --content "Always verify turnover warning threshold."
+briefops prime --task "Continue rebalance review" --format codex --max-tokens 800
+```
+
+`briefops codex plugin install` is local and deterministic. It does not publish to a marketplace and does not write to global Codex folders by default.
+
+`briefops export all` writes router files for Codex, Claude Code, and Cursor. These files point harnesses at BriefOps commands and do not copy `.briefops` memory, logs, handoffs, or worker summaries.
+
+## Persistent Worker Path
+
+After work finishes, log the result and promote only useful lessons:
+
+```bash
+briefops finish --project atlas-q --skill risk-review --worker quant-reviewer --task "Review rebalance" --result "Found missing turnover warning check." --lesson "Always verify turnover warning threshold."
+briefops approve latest
+briefops continue --worker quant-reviewer --task "Continue rebalance review" --pack
+```
+
+BriefOps skills must never auto-approve memory proposals or skill patches. Approval is a human step.
+
+For small or exploratory work, keep durable memory clean:
+
+```bash
+briefops finish --task "Fix typo" --result "Fixed typo." --importance trivial
+briefops finish --task "Try discarded approach" --result "Discarded." --no-memory-proposal
+briefops memory hygiene
+briefops memory prune --dry-run
+```
+
+## Shared-Only Export Path
+
+```bash
+briefops prime --task "Continue unresolved checks." --format codex --export-policy shared-only
+briefops pack resume --worker quant-reviewer --task "Continue unresolved checks." --export-policy shared-only
+```
+
+`shared-only` omits private memory, local project file details, raw work logs, open risks, local next steps, private worker lessons, private incidents, recent work history, and private metadata counts.
+
+`local-private` is intended for local terminal/Codex use only.
+
+## Privacy Check
+
+Before publishing a repository or sharing generated context, run:
+
+```bash
+briefops doctor --privacy
+briefops doctor --privacy --fix-gitignore
+```
+
+`.briefops/` can contain private local work logs and memory. Keep it ignored unless you intentionally curated the contents for sharing.
+
+`doctor --privacy` checks local memory sharing hazards, including `.briefops/` gitignore coverage, private/exportable memory, and secret-like memory strings.
+
+## Context Budget Check
+
+```bash
+briefops inspect budget
+briefops compare context --worker quant-reviewer --task "Continue rebalance review"
+```
+
+Use these before adding more always-loaded instructions. BriefOps works best when `prime` stays compact and full resume packs are generated only when needed.