fdeops 4.1.1 → 5.1.0

package/skills/fde/references/runbook.md

@@ -1,141 +1,73 @@
-# runbook - Write the runbook
+# runbook - Write an operating guide
 
-**Enter when:** the engagement is entering its final phase, the customer team needs to operate without the FDE, a new FDE is taking over, or the sponsor asks "what happens when you leave?"
+**Enter when:** the team needs instructions to operate, diagnose or recover a system, or an engineer is preparing to transfer responsibility.
 
-**Read first:** `delivery.md`, `terrain.md`, `reality.md`, `decisions.md`, `context.md`, `stakeholders.md`. The handoff is built from the full engagement record. Load `trust-profile.md` for operational boundaries.
+Apply [task context](task-context.md). Use supplied operational facts, relevant code and verified procedures. For a bound engagement, retrieve relevant sanitized delivery, dependency and ownership evidence; do not load the full customer record or raw private material.
 
-The mark of a great FDE engagement is that the team can operate without you. A handoff that requires a callback in six weeks means the engagement didn't end - it paused. Handoff engineering is deliberate: it's designed, tested, and verified before the last day.
+## Match the request
 
-## Method (you do this work)
+- **Draft a guide:** write what is known, mark unverified procedures and missing evidence, and return the requested document. No customer record, live access, drill or closure ceremony is required.
+- **Verify an operating guide:** agree the permitted environment and checks, exercise relevant procedures, and record what happened. Do not run a destructive or production drill from a documentation request alone.
+- **Complete a handoff:** use [handoff](close.md) for the wider ownership and acceptance decision. A written guide is one part of that decision, not proof of readiness.
 
-**1. The handoff inventory.** Everything the team needs to operate, categorised:
+## Build the guide from evidence
 
-| Category | What to hand off | Test: can they do it alone? |
-|----------|-----------------|---------------------------|
-| **Code knowledge** | Architecture decisions (`decisions.md`), why the code is shaped the way it is | Team member can explain the three most important design decisions |
-| **Operational** | Deploy, rollback, incident response, monitoring | Team member runs the deploy and rollback procedure independently |
-| **Tribal** | The things only you know - the workaround, the contact, the context | Written in `handoff.md` and reviewed with the person who'll carry it |
-| **Political** | Stakeholder dynamics, approval chains, who to call when | Documented in `stakeholders.md` with signal history |
-| **Data/AI** | Model versions, retraining triggers, drift monitoring, fallback paths | Owner named for each AI component; kill switch documented |
-
-**2. The 2am document.** Written for the person woken up on a Saturday night with zero context:
-
-```markdown
-# Operations runbook - <system name>
-
-## The 3 things that will break (and the fix for each)
-
-### 1. <most likely failure>
-Symptom: <what they'll see>
-Cause: <most likely why>
-Fix: <exact steps, copy-pasteable commands>
-Who to call if this doesn't fix it: <name, contact>
-
-### 2. <second most likely failure>
-...
-
-### 3. <third most likely failure>
-...
-
-## Deploy
-Command: <exact command>
-Time: <how long it takes>
-Verify: <how to confirm it worked>
-Rollback: <exact command and expected time>
-
-## Alerts
-| Alert | Means | Do this |
-|-------|-------|---------|
-| <alert name> | <plain English> | <action or link to detailed runbook> |
-
-## Contacts
-| Who | When to call | How |
-|-----|-------------|-----|
-| <name> | <scenario> | <phone/slack/email> |
-```
-
-**3. The knowledge transfer sessions.** Not a document dump - three structured sessions:
-
-| Session | Focus | Attendees | Duration | Output |
-|---------|-------|-----------|----------|--------|
-| **Architecture walkthrough** | Why, not what. The decisions, the trade-offs, the things that almost went wrong. | Full team | 60-90 min | Recording + Q&A log |
-| **Operational drill** | Deploy, rollback, incident response. They do it, you watch. | On-call team | 60 min | Drill report with confidence level |
-| **Floor drill** | They run the real job (the exception on the operating map) while you watch, hands off. Then they teach the next person. If they cannot, the runbook is a PDF. | Named operator on the floor | 45-60 min | They used the 2am doc during the drill, or the embed is not closed |
-| **Edge-case handover** | The things that aren't in any document. The workarounds, the fragile spots, the "ask Sarah because she's the only one who knows." | Team lead + 1 | 30 min | Additions to `handoff.md` |
-
-**4. The confidence check.** After the knowledge transfer, score the team's readiness:
-
-| Area | Confidence (1-5) | Evidence |
-|------|------------------|----------|
-| Daily operations | | Can they deploy and rollback without help? |
-| Incident response | | Did they complete the drill within acceptable time? |
-| Floor job | | Did the named operator complete Tuesday's real exception without you at the keyboard? |
-| Architecture decisions | | Can they explain why the system is built this way? |
-| AI components (if any) | | Do they know how to monitor, retrain, and disable? |
-| Stakeholder management | | Do they know who to update and how? |
-
-**Average below 3.5 → the handoff is not complete.** Extend, or tell the sponsor the embed is not closed. Do not document the gap and leave.
-
-**5. The successor brief.** If a new FDE is taking over, write a brief that gets them operational in one hour:
+Identify the system, the intended reader and the decisions that reader can make. Follow the actual operating path and include only relevant sections:
 
 ```markdown
-# Successor brief - <engagement name>
-
-## In 30 seconds
-<The real problem, the solution, where it stands>
-
-## Read these files first
-1. context.md - current state
-2. reality.md - the real problem (not the brief)
-3. decisions.md - what was decided and why
-4. stakeholders.md - who matters and their current signal
-5. risks.md - what's dangerous right now
-
-## The three things I wish I'd known on day one
-1. <thing>
-2. <thing>
-3. <thing>
-
-## The one thing that will bite you
-<specific warning>
+# Operating guide - <system>
+Status: Draft / Verified for <environment and scope>
+Evidence: <code, observed run, operator statement or existing document>
+Operating owner: <confirmed role/person and source, or proposed/unconfirmed>
+
+## Normal operation
+What should happen, how often, and how to check it.
+
+## Known failure modes
+Symptom: <what the operator sees>
+Evidence: <what establishes this behavior>
+Cause: <verified cause or explicit unknown>
+Action: <supported steps, constraints and stop conditions>
+Validation: <tested environment/date/result, or unverified>
+Escalation: <confirmed role/channel, or missing>
+
+## Deploy and recover
+Procedure: <verified commands or a source link; do not invent commands>
+Permissions and prerequisites: <required access and safety conditions>
+Check: <expected observable result>
+Recovery: <tested procedure or the missing recovery evidence>
+
+## Monitor and escalate
+Signal: <existing alert or check>
+Meaning: <known interpretation>
+Response: <authorized action and when to escalate>
+
+## Open readiness gaps
+Missing evidence, owner to confirm, and proposed next check.
 ```
 
-**6. The clean exit.** Before the last day:
-
-- [ ] All access returned or transferred (repos, environments, admin panels)
-- [ ] No personal credentials left in the system (API keys, tokens, SSH keys)
-- [ ] `.fde/` folder handed to the successor or archived with the team
-- [ ] Final status sent to sponsor (see `readout.md`)
-- [ ] Retrospective completed (see `close.md`)
-- [ ] Patterns extracted (see `encode-pattern.md`)
+Do not pad the document with an arbitrary number of failures, contacts or commands. A stated retry problem without a known cause should remain an investigation item, not become a fabricated repair procedure. A suggested owner is not an accepted operating responsibility.
 
-## Artifact
+For AI components, include relevant model and configuration versions, evaluation checks, failure limits and the supported way to pause actions. Do not assume retraining or autonomous operation is required.
 
-**`handoff.md`** - the 2am document + the operational inventory. The most important file the engagement produces after the code itself.
+## Verify when requested
 
-**`context.md`** - final update: engagement status, handoff confidence, named gaps.
+Select checks based on the system's actual consequences. For example, the receiving operator may demonstrate normal operation, diagnose a known failure, or recover a failed release in a permitted test environment.
 
-## Checkpoint
+Record each critical capability separately as verified, failed or untested, with evidence. A successful walkthrough cannot compensate for an untested recovery path. Avoid an averaged confidence score that hides a critical gap.
 
-The acid test: "Can the team run this system for 30 days without calling you?" If yes → handoff complete. If no → name exactly what's missing, and either fix it or document the risk for the sponsor.
+If a procedure fails, correct the guide or system within scope and repeat the affected check. If verification is unavailable, deliver the draft with its limits and propose the next check; do not claim the handoff complete or indefinitely extend the engagement yourself.
 
-## The permanent crutch anti-pattern
+## Deliver and retain ownership boundaries
 
-Warning signs you've become a dependency instead of a deliverer:
-- The team defers decisions until you're in the room
-- "Can you just stay one more month?" (translation: the handoff hasn't started)
-- You're the only person who's run the deploy or the rollback
-- The sponsor introduces you as "part of the team" in month 4
-- The customer calls you within a week of "close"
+Return the guide, its verification status and any remaining operating decisions. Save it to the requested location. In a bound engagement, propose updates to `handoff.md` and relevant current-state records under their confirmation rules.
 
-If you see 2+: accelerate the handoff immediately. The longer you stay past usefulness, the harder it is for the team to believe they can operate alone. A great FDE engagement ends with the team forgetting they needed you.
+Access changes, exports of customer records, sponsor messages and closure decisions require their own authorization. A request for a runbook does not authorize these actions. Transfer only the material the recipient is entitled to receive.
 
 ## Principles
 
-- The goal of every engagement is to make yourself replaceable.
-- The 2am document is the real handoff - everything else supports it.
-- Knowledge transfer is four sessions, not a doc dump. The floor drill is the named operator completing Tuesday's real job from the 2am doc, hands off. If they cannot, do not close.
-- A confidence score below 3.5 means the handoff isn't done.
-- The successor brief gets the next FDE operational in one hour or it's too long.
-- Clean exit: no personal credentials left behind, ever.
-- If you're still indispensable after close, the engagement failed on the most important criterion.
+- Write for the person handling the actual failure.
+- Supported procedures beat plausible commands.
+- Draft, tested procedure and accepted ownership remain distinct.
+- Verify critical capabilities individually.
+- Keep private relationship notes and credentials out of an operating guide.

package/skills/fde/references/source-setup.md

@@ -0,0 +1,30 @@
+# Source access for customer notes
+
+Use this guide when `connect` needs a source and when `ingest` cannot reach requested material. Configure only the named source. FDEOps does not bundle source authentication or silently install integrations.
+
+## Start with what is already available
+
+Inspect the current host's tools. Name which requested source can be read and what remains unavailable. A server appearing in a configuration file is not proof that its credentials or scopes work.
+
+For setup, use the source provider's current official documentation and the host's documented connector or MCP configuration. Do not invent package names, API methods, secret values or installation flags. Prefer an existing authenticated connector over adding a second one. Put credentials in the host's supported secret storage; never paste them into a customer record, prompt or report.
+
+## Choose the source path
+
+| Material | First check | If unavailable |
+|---|---|---|
+| Pasted notes or a local export | The user permits this content in the agent; identify the relevant file or text | Ask for the specific missing material, not an integration installation |
+| Meeting notes, such as Granola | A notes tool can read the selected meeting and its source identifier | Use a permitted export or the provider's supported setup |
+| Slack or another chat system | Read access to the specified thread or channel and date range | Ask the user or workspace owner to resolve access; a copied thread is an alternative |
+| Notion or another document system | Read access to the specified page and its linked content when required | Use a permitted document export or resolve the missing page access |
+
+Test a configured source with the smallest requested read. Report setup, connectivity and successful retrieval separately. Do not widen access to an entire inbox or workspace just because one item is unavailable.
+
+## Keep setup separate from record updates
+
+Configuring or testing a source does not require a customer record. Reading requested material does not authorize applying it to one.
+
+For a review-only request, use the permitted supplied or fetched text and return a sourced draft. For staging or saving, select the intended customer record first, then follow [ingest](ingest.md): stage → propose → review → explicit confirmation → apply. Source permissions do not authorize a record update, and the FDEOps CLI itself makes no network calls.
+
+Short notes can use [debrief](debrief.md) directly. Large files should be staged through the CLI when a customer record has been selected. Preserve source IDs and dates when available; absence of a source remains explicit.
+
+FDEOps does not post messages, change source documents, background-sync channels or make recurring pulls through this path. Use the requested read scope only.

package/skills/fde/references/task-context.md

@@ -2,11 +2,17 @@
 
 Use this contract for standalone methods and methods routed through `@fde`.
 
-- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
+- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite for work on supplied context. Tasks that inspect actual records need those records; staging or saving requires a selected customer. Never fabricate records to make an operational task appear complete. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
 - **Artifact names are destinations:** names such as `success.md`, `decisions.md`, and `delivery.md` identify relevant evidence and, when bound, record destinations. If absent, use supplied facts and return the requested draft or result in the current workspace or conversation. Do not invent files or require initialization to complete useful work.
 - **Bound engagement:** honor the current client binding and constraints. Before reading records, run `fde privacy` to verify masking support. Obtain a fresh, identity-matching sanitized `fde resume` packet for this task (or reuse a fresh session-hook packet); retrieve missing evidence with targeted `fde recall <topic>`. Use bounded `fde handoff` for transfer work. Refresh after binding, masking, or record changes. Never substitute raw `.fde/` reads, private blocks, masking dictionaries, or full transcripts. If the CLI is unavailable, use only permitted supplied excerpts and report the context limitation.
 - **Authority:** continue reversible work within authorized scope. Reuse prior authorization when it covers the specific action. Show consequential engagement-record judgments and uncertainties for confirmation before saving unless already explicitly confirmed. New scope, acceptance changes, production actions, exports, and external messages need the applicable authority; a method invocation alone does not supply it. Keep one customer's writes in that customer's record.
 - **Evidence:** distinguish supplied facts, estimates, hypotheses, and unknowns. Cite actual sources; a log date is not attribution. Never invent a source, signer, signature, customer reaction, or acceptance. Keep outcomes **promised → measured → accepted** distinct, and implementation, verification, deployment, and customer acceptance separate. Missing evidence means unproven, not an observed failure.
 - **Data boundary:** use only data permitted by the customer's AI policy; clarify unknown policy before loading their code or data. Never load `<private>` content into a model. Cross-client comparison and exporting reusable material require permission and removal of customer-identifying or confidential content; anonymization alone does not grant permission.
 
+## CLI availability
+
+Only locate the CLI when the selected task needs it. Check `fde` on PATH and its `fde privacy` capability before reading records. If unavailable, use `node ~/.claude/fdeops/fde.js` when the disk installer placed it there, or `npx --yes fdeops <command>` when package downloads are permitted. Respect local installation and network rules. Run commands for the user; do not turn a missing bare `fde` command into unnecessary manual setup.
+
+If no permitted executable is available, explain the missing capability. Continue any useful draft from supplied excerpts, but do not claim to have read, switched, staged, saved or rendered real records. Do not read raw private record files as a fallback.
+
 Apply the selected method to this context. Follow its linked supporting methods only when needed; do not restart discovery or repeat already answered questions.

package/skills/feedback/.fde-generated.json

@@ -0,0 +1,9 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "f8666990f8b4463af5f29acdb1d1cd5e8fec68119b82a891aa2322a213f37344",
+    "references/encode-pattern.md": "3be7bf9d0f69af31659423c54d6023a4af1556e2ce200fb025bf64d0757de4d8",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/{fde-feedback → feedback}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: fde-feedback
+name: feedback
 description: Assess a field lesson for reuse or product feedback without exposing customer context. Use for recurring deployment lessons; distinguish a hypothesis from a validated pattern.
 ---
 
-# fde-feedback
+# feedback
 
 <!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
 

package/skills/feedback/references/task-context.md

@@ -0,0 +1,18 @@
+# Task context and evidence
+
+Use this contract for standalone methods and methods routed through `@fde`.
+
+- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite for work on supplied context. Tasks that inspect actual records need those records; staging or saving requires a selected customer. Never fabricate records to make an operational task appear complete. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
+- **Artifact names are destinations:** names such as `success.md`, `decisions.md`, and `delivery.md` identify relevant evidence and, when bound, record destinations. If absent, use supplied facts and return the requested draft or result in the current workspace or conversation. Do not invent files or require initialization to complete useful work.
+- **Bound engagement:** honor the current client binding and constraints. Before reading records, run `fde privacy` to verify masking support. Obtain a fresh, identity-matching sanitized `fde resume` packet for this task (or reuse a fresh session-hook packet); retrieve missing evidence with targeted `fde recall <topic>`. Use bounded `fde handoff` for transfer work. Refresh after binding, masking, or record changes. Never substitute raw `.fde/` reads, private blocks, masking dictionaries, or full transcripts. If the CLI is unavailable, use only permitted supplied excerpts and report the context limitation.
+- **Authority:** continue reversible work within authorized scope. Reuse prior authorization when it covers the specific action. Show consequential engagement-record judgments and uncertainties for confirmation before saving unless already explicitly confirmed. New scope, acceptance changes, production actions, exports, and external messages need the applicable authority; a method invocation alone does not supply it. Keep one customer's writes in that customer's record.
+- **Evidence:** distinguish supplied facts, estimates, hypotheses, and unknowns. Cite actual sources; a log date is not attribution. Never invent a source, signer, signature, customer reaction, or acceptance. Keep outcomes **promised → measured → accepted** distinct, and implementation, verification, deployment, and customer acceptance separate. Missing evidence means unproven, not an observed failure.
+- **Data boundary:** use only data permitted by the customer's AI policy; clarify unknown policy before loading their code or data. Never load `<private>` content into a model. Cross-client comparison and exporting reusable material require permission and removal of customer-identifying or confidential content; anonymization alone does not grant permission.
+
+## CLI availability
+
+Only locate the CLI when the selected task needs it. Check `fde` on PATH and its `fde privacy` capability before reading records. If unavailable, use `node ~/.claude/fdeops/fde.js` when the disk installer placed it there, or `npx --yes fdeops <command>` when package downloads are permitted. Respect local installation and network rules. Run commands for the user; do not turn a missing bare `fde` command into unnecessary manual setup.
+
+If no permitted executable is available, explain the missing capability. Continue any useful draft from supplied excerpts, but do not claim to have read, switched, staged, saved or rendered real records. Do not read raw private record files as a fallback.
+
+Apply the selected method to this context. Follow its linked supporting methods only when needed; do not restart discovery or repeat already answered questions.

package/skills/{fde-handoff → handoff}/.fde-generated.json

@@ -2,9 +2,9 @@
   "generator": "bin/generate-skills.js",
   "version": 1,
   "files": {
-    "SKILL.md": "81250bf05e9edab5128a9ae72d2c33aac7e3a0d3dbdfbaaaa8352e21f81d0323",
+    "SKILL.md": "9f08605914670f2c0bd09631d3d40c079e7f63174d1a2607e60ea6eca5d54d93",
     "references/close.md": "095266722624e4bc647628243c8be0e69b02017ef6b4e3a7e7790ec1f53ab7c0",
     "references/encode-pattern.md": "3be7bf9d0f69af31659423c54d6023a4af1556e2ce200fb025bf64d0757de4d8",
-    "references/task-context.md": "8ec90708522e512a50a57ab2a377a7472e93bae169c6f075a93fa603ce2ad780"
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
   }
 }

package/skills/{fde-handoff → handoff}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: fde-handoff
+name: handoff
 description: Transfer operation of a customer deployment with ownership, evidence and a tested support path. Use for handoff or an engineer rotation, not merely code delivery.
 ---
 
-# fde-handoff
+# handoff
 
 <!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
 

package/skills/handoff/references/task-context.md

@@ -0,0 +1,18 @@
+# Task context and evidence
+
+Use this contract for standalone methods and methods routed through `@fde`.
+
+- **Standalone work:** use the supplied, permitted facts, notes, code, and artifacts. A client name, `.fde/` directory, or initialized engagement is not a prerequisite for work on supplied context. Tasks that inspect actual records need those records; staging or saving requires a selected customer. Never fabricate records to make an operational task appear complete. Do not bootstrap records merely to run a method. Ask only for missing information or authority that changes the next action; mark other gaps as unknown.
+- **Artifact names are destinations:** names such as `success.md`, `decisions.md`, and `delivery.md` identify relevant evidence and, when bound, record destinations. If absent, use supplied facts and return the requested draft or result in the current workspace or conversation. Do not invent files or require initialization to complete useful work.
+- **Bound engagement:** honor the current client binding and constraints. Before reading records, run `fde privacy` to verify masking support. Obtain a fresh, identity-matching sanitized `fde resume` packet for this task (or reuse a fresh session-hook packet); retrieve missing evidence with targeted `fde recall <topic>`. Use bounded `fde handoff` for transfer work. Refresh after binding, masking, or record changes. Never substitute raw `.fde/` reads, private blocks, masking dictionaries, or full transcripts. If the CLI is unavailable, use only permitted supplied excerpts and report the context limitation.
+- **Authority:** continue reversible work within authorized scope. Reuse prior authorization when it covers the specific action. Show consequential engagement-record judgments and uncertainties for confirmation before saving unless already explicitly confirmed. New scope, acceptance changes, production actions, exports, and external messages need the applicable authority; a method invocation alone does not supply it. Keep one customer's writes in that customer's record.
+- **Evidence:** distinguish supplied facts, estimates, hypotheses, and unknowns. Cite actual sources; a log date is not attribution. Never invent a source, signer, signature, customer reaction, or acceptance. Keep outcomes **promised → measured → accepted** distinct, and implementation, verification, deployment, and customer acceptance separate. Missing evidence means unproven, not an observed failure.
+- **Data boundary:** use only data permitted by the customer's AI policy; clarify unknown policy before loading their code or data. Never load `<private>` content into a model. Cross-client comparison and exporting reusable material require permission and removal of customer-identifying or confidential content; anonymization alone does not grant permission.
+
+## CLI availability
+
+Only locate the CLI when the selected task needs it. Check `fde` on PATH and its `fde privacy` capability before reading records. If unavailable, use `node ~/.claude/fdeops/fde.js` when the disk installer placed it there, or `npx --yes fdeops <command>` when package downloads are permitted. Respect local installation and network rules. Run commands for the user; do not turn a missing bare `fde` command into unnecessary manual setup.
+
+If no permitted executable is available, explain the missing capability. Continue any useful draft from supplied excerpts, but do not claim to have read, switched, staged, saved or rendered real records. Do not read raw private record files as a fallback.
+
+Apply the selected method to this context. Follow its linked supporting methods only when needed; do not restart discovery or repeat already answered questions.

package/skills/ingest/.fde-generated.json

@@ -0,0 +1,12 @@
+{
+  "generator": "bin/generate-skills.js",
+  "version": 1,
+  "files": {
+    "SKILL.md": "4df02c561ea8d2baf66ac373d67527c8826b72d80bf7b1fedc248c45a572adf9",
+    "references/connect.md": "37ad703ece7fe3596be4d5d3697cc4ba5e6062615f9576733c20d055fc3e4927",
+    "references/debrief.md": "2d2db9a177f5341a9a2721a9d6ea32a6d07e7e982e621429ca408a38bc5617c1",
+    "references/ingest.md": "24880bc3d95cda09ec6c2f5edebd17fba99deb912f93e15c8b715a287283da84",
+    "references/source-setup.md": "a28ae7c6dbb2573a66f31b30b7abca34bc52573fe34d48fff4c7490e4dc85d3e",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490"
+  }
+}

package/skills/ingest/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: ingest
+description: Fetch requested source material and prepare sourced engagement updates. Use to catch up from external notes or messages; applying updates requires a bound record and confirmation.
+---
+
+# ingest
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Fetch requested source material and prepare sourced engagement updates. Use to catch up from external notes or messages; applying updates requires a bound record and confirmation.
+
+Read [the task context contract](references/task-context.md), then [the method](references/ingest.md). Load further references only when the task needs them. Everything linked is included in this skill; no other skill pack is required.
+
+## Principles
+
+- Use permitted supplied material or available source tools to prepare a sourced proposal without requiring an engagement record. CLI staging and reconciliation use a bound engagement; applying updates requires the bound record and confirmation. Do not claim an unbound draft has been saved to engagement memory.
+- If called by @fde, reuse its current sanitized packet and scope. Do not restart setup, discovery or questions already answered.
+- The task context contract controls persistence and authority in both modes. Preserve unknowns and distinguish implementation, verification, deployment and acceptance.
+- Use the customer's repository instructions and available tools. Report a missing capability or unrun check honestly; do not claim that installing a skill provisions infrastructure.

package/skills/ingest/references/connect.md

@@ -0,0 +1,24 @@
+# connect - Connect a source
+
+**Enter when:** the user asks to connect a notes, chat or document source, or an expected source cannot be read.
+
+Apply [task context](task-context.md). Source setup can run independently of a customer record. Follow [source setup](source-setup.md) for permitted tools, credentials, connectivity checks and export alternatives.
+
+## Method
+
+1. Identify the source and the material the user wants to read. Inspect the host's actual available tools before recommending setup.
+2. If the source already works, use a narrowly scoped requested read. Do not install another connector.
+3. If setup is needed, verify current provider and host documentation, explain the required access, and make only authorized configuration changes. Never put credentials into prompts or customer records.
+4. Test the selected source and distinguish configuration from successful retrieval. If access is blocked, report the specific limitation and an available file or paste alternative.
+5. If the user also wants to update a customer record, continue with [ingest](ingest.md) after selecting that record. Otherwise stop after the requested setup or read.
+
+## Checkpoint
+
+Return what is connected, what read was verified, any access gap, and how to request the next pull. Do not claim an integration works from configuration alone or write customer records during setup.
+
+## Principles
+
+- Existing source tools first; configuration only when needed.
+- Minimum requested read, no ambient synchronization.
+- Credentials stay in supported secret storage.
+- Record updates require their own review and confirmation.

package/skills/ingest/references/debrief.md

@@ -0,0 +1,91 @@
+# debrief - Capture the meeting
+
+**Enter when:** the FDE just left a meeting/call and dumps raw notes, a transcript, or "they said…". Highest-frequency moment in FDE life. Capture within the hour.
+
+**Standalone review:** apply [task context](task-context.md). If the user supplies notes and wants a summary or review, interpret them using **Prepare one update** below and return a draft. Keep requests, confirmed decisions, reported results and unknowns distinct. No CLI or customer record is needed; do not claim anything was saved. Use the bound-record path below only when updating an existing record or when the user asks to start one.
+
+**Large transcripts or emails** sitting in Granola/Gmail/Notion → prefer **`fde ingest stage`** first (via source MCPs the FDE configured), then the same propose → confirm → **`fde ingest apply`** path. See `references/ingest.md`. Pasted short notes stay on this debrief verb.
+
+**Read first:** the bounded `fde resume` packet for the bound client. Use `fde recall` for the specific prior decision, action, or delivery result needed to reconcile this update. Do not reload the whole engagement.
+
+**Who runs the CLI:** you (the agent). Never tell the FDE to type `fde debrief …`.
+
+## Honest contract (read once)
+
+- The `fde` CLI is **local, deterministic, no AI**. `--smart` is a **gate + writer**, not a brain.
+- It keeps lines that already have `decision:` / `risk:` / `delivery:` / `contact:` / `next:` / `signer:` prefixes, plus a thin keyword pass (e.g. "we agreed", person+verb lines, "open question", "X signs off").
+- `signer: Priya` fills **Stakeholder who signs off** in `success.md` and logs Priya as a contact. The CLI proposes it when a sentence says someone signs off / approves / has final say. If the notes name who can say yes and the proposal does not carry a `signer:` line, add one - that is the most expensive sentence in the meeting.
+- Heuristics can miss facts **and mislabel prefixed lines**. You interpret every candidate against the sanitized source, not just unprefixed lines. Split distinct decisions, requests, actions, and results; keep uncertainty. The user reviews meaning, never prefix syntax.
+- `.debrief-propose` is raw lines only (no routing annotations). "Edit if mis-routed" means **rewrite the line with the right prefix**, not leave a comment in the file.
+
+## Method (you do this work)
+
+### Preferred path - smart debrief (messy notes)
+
+1. Save the FDE's notes to a temp `.md` file in the workspace (or pipe stdin).
+2. Run `fde debrief --smart <notes.md>` (or `npx fdeops debrief --smart …`).
+3. Run `fde debrief --review` before opening an existing proposal so legacy identifiers are masked. Open the proposal only after review succeeds. Never open a proposal containing manually inserted raw private blocks. Prepare the pending proposal using **Prepare one update** below. Read only the sanitized `.debrief-propose`, never the sealed private sidecars or raw private source. Preserve privacy markers, source metadata, and complete identifier aliases such as `[[email:...]]`. The CLI restores known aliases locally on apply. Never read `.privacy/` or try to recover an identity with file tools. If an alias is truncated, retrieve a narrower excerpt; never guess or edit the token.
+4. Run `fde debrief --review` after editing. Treat the CLI REVIEW and routing output as your validation, not a second presentation to the user. Resolve errors and replay warnings before asking for confirmation.
+5. Show **one** concise review in chat: name the client, then the consequential changes in plain English. Include decisions, requests still unagreed, actions, reported delivery, signer or contact changes, and unresolved conflicts when present. Show the previous value only where it changes the meaning. Omit empty categories and CLI routing details; do not impose a fixed four-row card that hides other changes. If the proposal is too large to show faithfully, split the review into explicit batches; never approve hidden changes.
+6. Ask **Save this update?** This confirms the engineer's record, not customer acceptance. On confirmation, apply precisely that proposal with `fde debrief --apply`. A material correction requires a revised review and renewed confirmation. On rejection, leave the proposal pending and do not apply.
+7. Verify the changed facts through bounded `fde resume` / targeted `fde recall`. If a fieldbook is part of the current task, regenerate it using the existing command and destination after the confirmed save; do not make the user run it. End with a brief saved/not-saved result and the next action, not another full summary.
+
+### Prepare one update (shared with ingest)
+
+Do this work yourself before the human review:
+
+- **Check meaning, not keywords.** “We settled on delaying the rewrite” is a decision; “Mara will request access” is an action, even if the heuristic calls it a contact. A wish or suggestion remains a request, not agreement. Do not infer authority, approval, a calendar date from an unanchored relative date, or production value from staging.
+- **Make interpretation visible in the same review.** For messy or dictated input, separate consequential statements supplied by the user from your proposed interpretation. Leave a missing model, date, owner, or scope explicitly unknown; do not fill it from what seems usual. Include only interpretation calls that could change the work, not a second recap or extra approval step.
+- **Handle changed minds without erasing history.** If the same speaker clearly corrects their own instruction ("send it Friday; actually, wait for Monday's review"), show the superseded instruction and the replacement together. Different speakers, uncertain chronology, or a new request conflicting with recorded authority remain a conflict to resolve, not permission to choose the last sentence. Keep consequential parked requests pending; omit conversational tangents. Never mark an inferred change as agreed.
+- **Keep facts traceable.** Preserve supplied source locators on each consequential fact, using `[source: ...]`. If only a local file or staged item exists, cite that actual locator as a note source, not a customer receipt. Do not invent a meeting date or speaker. A source label is not authenticated approval.
+- **Reconcile only what changed.** Compare affected facts with the current record using targeted retrieval. Leave unchanged sourced statements out of an accidental re-import. Preserve earlier history; record changed or conflicting claims explicitly. If everything is already recorded, say so and leave the pending proposal unapplied. If it blocks a later capture, explain that no new facts were saved and ask permission to replace that pending review; use `--replace-proposal` with the new notes only after that authorization. Do not delete proposal files or private sidecars manually. Do not use `--allow-replay` without explicit approval of an intentional repeat.
+- **Protect the current next action.** A late meeting note does not automatically supersede a newer action. Keep older actions as dated context unless their current priority is established; show a conflict when it needs a decision. Use exactly one physical `next:` line for the current action. If multiple current actions are explicitly agreed, include them on that same line separated by semicolons; the CLI retains only the last `next:` line. Keep other dated commitments in context. Do not silently discard other commitments.
+- **Keep memory useful.** Retain consequential facts and indispensable context; remove chatter and repetition from the proposal, not from the source. Preserve the raw input outside `.fde/` (staged material stays in `.inbox/`). Never remove privacy placeholders or modify sealed sidecars. Ask only about a consequential ambiguity that cannot remain explicitly unknown.
+- **Structure the result.** Use `decision:` / `risk:` / `delivery:` / `contact:` / `next:` / `signer:`. Preserve `ask:` / `scope:` as explicitly proposed context when appropriate. Prepare the seven-field delivery row yourself for a reported result (see below); unknown fields stay `pending`. The human should not have to fill out a ledger to capture a meeting.
+
+Before showing the review, check that every consequential fact in the sanitized source is represented, already recorded, or explicitly unresolved. Check classified lines as carefully as unclassified ones. Nothing is saved simply because this preparation is complete.
+
+### Fallback - you structure, then route
+
+If `--smart` is unavailable or you already have clean prefixes:
+
+1. Extract into buckets - **only what was actually said**:
+   - **Decisions** - agreed, by whom, in their words where possible
+   - **Action items** - owner + due; unowned → `owner: unknown - ask`
+   - **Stakeholder signals** - tone shifts with evidence → green/amber/red
+   - **Risks** - new / confirmed / retired
+   - **Open questions** - what to chase next
+2. Format lines as `decision:` / `risk:` / `delivery:` / `contact:` / `next:` / `signer:` (contacts may end with `[signal:green|amber|red]`).
+3. Follow **Prepare one update** and show the same single plain-English review as the preferred path. Include every consequential change and ask **Save this update?**.
+4. On confirm, pipe to `fde debrief` (or write a file and run it).
+
+Ask at most one focused question at a time when ambiguity would change the record. Otherwise preserve the unknown and include it in the review. Never treat silence as confirmation.
+
+## Artifact
+
+- Smart apply / debrief CLI writes the dated routes into the right `.fde/` files.
+- `next:` updates the existing `## Next action` in `context.md` (collapses duplicates). Do not append a second `## Next action` heading by hand.
+- If you must write directly: decisions → `decisions.md`; signals → `stakeholders.md` Signal history; risks → `risks.md`; next actions → fill under the template `## Next action` in `context.md`. Prefer the CLI.
+
+## Checkpoint
+
+Use the single pre-save review above. After saving, report verification and the next action briefly; do not ask for a second approval or repeat the review.
+
+## Principles
+
+- Capture within the hour or lose the nuance.
+- Verbatim quote outranks paraphrase; hesitation outranks quote.
+- Signals move on evidence, never on vibe alone.
+- A meeting with no decisions and no actions - say so; that is a finding.
+
+## Delivery rows and repeated updates
+
+For a measured or promised slice, use a reviewed structured line:
+
+```text
+delivery: Replay|risk-mitigation|zero duplicates|zero duplicates on staging|pending|[source: transcript:42]|pending
+```
+
+The seven fields are Slice, Bucket, Promised, Measured, Accepted by, Evidence, Rollback. Keep unknowns `pending`; never infer approval. This lands in the value ledger during the same confirmed apply. A `delivery:` line without pipes stays a narrative note. Incorrect field counts refuse the write rather than shifting the meaning of cells.
+
+A sourced statement already in the record triggers a replay warning. Before applying, compare newer facts and the current next action. Remove repeated statements from the proposal if this is an accidental re-import. Only after the engineer explicitly confirms an intentional repeat, apply with `fde debrief --apply --allow-replay`. This does not silently deduplicate history and does not authenticate sources.

package/skills/ingest/references/ingest.md

@@ -0,0 +1,75 @@
+# ingest - Ingest sources
+
+**Enter when:** the FDE wants to catch the engagement up from external sources - "make sure Acme is up to date," "pull what's relevant," "grab today's Granola and Denise's last email." Raw transcripts and long emails that are too big to paste usefully.
+
+**Connect / capability (different entry):** "connect a new MCP", "connect Granola/Slack/Notion", "what can you pull?" → `references/connect.md` first. Use [source setup](source-setup.md) for files and supported source tools.
+
+**Review only:** requested source reads and a sourced draft can proceed without a customer record. Use [source setup](source-setup.md) and [debrief](debrief.md). Do not stage or apply anything until the intended customer is selected; do not silently create a record for a review-only request.
+
+**Read first:** the bounded `fde resume` packet and targeted recall for affected prior facts. Bind the engagement before staging anything.
+
+**Who runs the CLI:** you (the agent). Never tell the FDE to type `fde ingest …`. Never auto-apply. Never background-sync or poll sources on your own.
+
+## Honest contract (read once)
+
+- FDEOps owns the **sink only**: stage raw pulls → propose → confirm → apply. Nothing writes `.fde/` unreviewed.
+- **Source MCPs are the FDE's.** Granola, Slack, Notion, Gmail, custom - whatever they configured in Cursor/Claude. fdeops does not bundle OAuth, connectors, or ambient sync, and **does not push** to those tools.
+- Prefer **`fde ingest` in this bound workspace.** Optional `fdeops-ingest` MCP: pass `engagement` (path to `.fde/` from `fde resume --bind`) because MCP cwd often is not the client workspace.
+- The core `fde` CLI stays local (git + file reads). Source credentials live with that MCP; fdeops never stores them.
+- After apply, raw stays in `.inbox/`; the system of record (`.fde/`) stays thin dated facts.
+
+## Capability check (before every pull)
+
+List what you can actually call **this session**:
+
+1. **Sink** - `ingest_stage` / `fde ingest` available?
+2. **Sources** - which fetch tools exist (Granola-shaped, Slack, Notion, Drive, file-only)?
+3. Tell the FDE in one line: *I can pull from X; Y is not connected.* If they asked to pull Y and it is missing → switch to `connect.md`. Never pretend a source exists.
+
+## Ground loop (you do this work)
+
+1. **Bind** the engagement (`fde resume` / registry). If multiple meetings or threads could apply, ask **one** clarifying question - which meeting, which thread, which date range.
+2. **Capability check** (above). Then **fetch** via available source MCP(s). You pull; the CLI does not reach the network.
+3. **Stage** - `fde ingest stage [--source NAME] [--title TEXT] [file|-]` writes raw text into `<engagement>/.inbox/` (outside the memory git ledger).
+4. **List** (optional) - `fde ingest list` shows staged items when you need an id or filename.
+5. **Propose** - `fde ingest propose <id-or-filename>` runs the debrief `--smart` path on the staged body (+ provenance line). Opens `.debrief-propose`.
+6. **Prepare** - follow **Prepare one update** in `references/debrief.md`. Interpret every sanitized candidate, including already-prefixed lines; reconcile changed facts, preserve source locators, and keep raw chatter out of memory. Preserve privacy placeholders and sealed sidecars.
+7. **Validate and show** - run `fde debrief --review` after editing, then show the same single plain-English review as debrief, including delivery changes and conflicts. Ask **Save this update?** and wait for confirmation. CLI output is agent validation, not a second user review.
+8. **Apply and verify** - on FDE confirm only → `fde ingest apply` (= `fde debrief --apply`), then verify affected facts through bounded resume/recall. Refresh the current fieldbook if it is part of this task. On reject, leave the proposal pending; material edits require a revised review.
+
+No invented names, meetings, or quotes. If the propose looks wrong, fix prefixes with judgment, then re-show before apply.
+
+## Paths
+
+| Path | Role |
+|------|------|
+| `~/fde-engagements/<slug>/.inbox/` | Staging for raw pulls. Not the memory ledger. NDA surface - same home tree as `.fde/`. |
+| `~/fde-engagements/<slug>/.fde/` | System of record (unchanged contract). |
+| `.fde/.debrief-propose` | Propose file (shared with debrief). |
+
+## CLI verbs
+
+```bash
+fde ingest stage [--source NAME] [--title TEXT] [file|-]
+fde ingest list
+fde ingest propose <id-or-filename>
+fde ingest apply
+```
+
+## Provenance
+
+Carry an actual `[source: ...]` locator on each consequential fact. Preserve upstream IDs or links when supplied; otherwise cite the staged item path as a note source. Retain its `via:` metadata, but do not treat a standalone `via:` line as a source marker for every fact or as proof of approval. Re-imports still require semantic comparison; exact replay protection is not semantic deduplication.
+
+## MCP sink + recipes
+
+Optional `mcp/fdeops-ingest` wraps the same verbs over stdio. Source MCPs remain separate - the FDE adds whichever fetch tools they trust. Setup coach: `connect.md`. Portable setup guidance: [source setup](source-setup.md).
+
+## Checkpoint
+
+Use the single review from debrief: identify the client and sources, show consequential changes, then wait. Do not add another summary or approval step.
+
+## Principles
+
+- Pull on request, not on a schedule. No auto-poll, no vacuum of inbox or Slack. No posting back.
+- Staging is not memory. Only `--apply` after confirm writes `.fde/`.
+- Large artifact → ingest stage first; pasted short notes → debrief verb directly (`references/debrief.md`).