fdeops 5.0.0 → 5.1.0

package/skills/earn-trust/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: earn-trust
+description: Plan how to earn customer trust and appropriate access. Use when credibility, permissions or AI policy constrain the engagement.
+---
+
+# earn-trust
+
+<!-- Generated by bin/generate-skills.js; edit the canonical references and catalog. -->
+
+## Purpose
+
+Plan how to earn customer trust and appropriate access. Use when credibility, permissions or AI policy constrain the engagement.
+
+Read [the task context contract](references/task-context.md), then [the method](references/earn-trust.md). Load further references only when the task needs them. Everything linked is included in this skill; no other skill pack is required.
+
+## Principles
+
+- Work directly from the supplied permitted context. Standalone work does not require an engagement folder or initialization. Record filenames in the method are optional persistence destinations when no engagement is bound.
+- 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/earn-trust/references/earn-trust.md

@@ -0,0 +1,100 @@
+# earn-trust - Earn access
+
+**Enter when:** new engagement where you don't have full access yet, trust is thin, the customer said "let's start small," or you need to navigate "we don't trust AI-generated code."
+
+**Read first:** `trust-profile.md`, `stakeholders.md`, `context.md`. The trust profile tells you where the walls are; the stakeholder map tells you who built them.
+
+Trust is the currency of FDE work. Code quality gets you a second week; trust gets you the engagement. It's earned in small, visible moves - never demanded, never assumed, and never recovered once burned.
+
+## Method (you do this work)
+
+**1. The trust ladder - every engagement climbs it in order:**
+
+```
+Level 0: Observer     → read-only access, watching
+Level 1: Advisor      → recommendations, no code changes
+Level 2: Contributor  → PRs reviewed by their team
+Level 3: Committer    → direct push to feature branches
+Level 4: Owner        → production access, deploy authority
+Level 5: Trusted      → they call you before making decisions
+```
+
+**Never skip a level.** The FDE who asks for production access on day two gets observer access for a month. The FDE who ships a clean PR on day two gets committer access by week two. Each level is earned by demonstrating competence AND respect at the current level.
+
+**2. The first-week trust plays - specific, not generic:**
+
+| Day | Move | Why it works |
+|-----|------|-------------|
+| 1 | Fix a small, visible, annoying bug - something the team has been stepping over (only after `success.md` has a signer, or the FDE overrides with the unknown still visible) | Proves you can ship in their environment without breaking things |
+| 1 | Ask the passed-over team what naming conventions they use - then use them | Shows respect before competence |
+| 2 | Send a one-paragraph status to the sponsor without being asked | Sets the pattern: they hear from you before they have to ask |
+| 3 | Find a genuine risk and flag it without drama | Demonstrates you're protecting them, not performing |
+| 5 | Show a small win to the champion so they can share it upward | Gives them evidence their bet on you was right |
+
+**3. Navigate "we don't trust AI-generated code":**
+
+This is increasingly common. The right response is respect, not persuasion:
+
+- **Ask the policy, don't assume.** "Does your organisation have a position on AI-assisted code in production?"
+- **If prohibited:** work without AI on their code. Use fdeops for engagement memory (`.fde/` files) and your own planning - that's your tooling, not theirs.
+- **If permitted with review:** every AI-touched line goes through their normal review process. Flag it: "AI-assisted, human-reviewed" in commit messages if they want traceability.
+- **If grey area:** treat as prohibited until someone with authority says otherwise. The cost of asking is zero; the cost of guessing wrong is the engagement.
+- **Never hide it.** An FDE caught using prohibited AI tools loses the engagement and the reputation. Full stop.
+
+**4. Trust recovery - when you've made a mistake:**
+
+Mistakes happen. What matters is speed and honesty:
+
+- **Own it in the first hour.** Not "we found an issue" - "I introduced this bug." Passive voice erodes trust faster than the mistake.
+- **Show the fix AND the prevention.** "Here's what happened, here's the fix, here's the test that prevents it next time."
+- **One visible win within 48 hours.** Trust recovery needs a concrete success close to the mistake - not weeks later.
+- **Never minimise.** "It was a small bug" is your assessment, not theirs. Let them size it.
+
+**5. The trust account - deposits and withdrawals:**
+
+| Deposits (slow, steady) | Withdrawals (fast, expensive) |
+|-------------------------|-------------------------------|
+| On-time status updates | Surprises - especially bad ones they hear from someone else |
+| Using their conventions | "I know better" energy - even when you do |
+| Flagging risks early | Breaking something in production |
+| Crediting the internal team | Taking credit for shared work |
+| Asking before touching sensitive code | Assuming access you haven't been given |
+| Over-communicating during incidents | Going quiet when things are hard |
+
+## Artifact
+
+**`trust-profile.md`** - updated sections:
+```markdown
+## Trust level
+Current: <level 0-5> as of <date>
+Evidence: <what earned this level>
+Next target: <level> - requires: <specific action>
+
+## AI policy
+Status: <prohibited / permitted-with-review / grey-area-treating-as-prohibited>
+Source: <who confirmed, when>
+```
+
+**`decisions.md`** - log trust-significant moves: "Flagged migration risk to ops lead before they discovered it (Day 3) - trust deposit."
+
+## Checkpoint
+
+One question to the FDE: "Are we at the right trust level for what we need to do next week?" If not: name the gap, name the move, and put it in `context.md` as the next action.
+
+## The week 2-4 valley
+
+Week 1 is the honeymoon - everyone's excited, access is fresh, the brief is new. Weeks 2-4 are the valley: novelty wears off, real problems surface, the sponsor's patience shifts from "take your time" to "when do we see results." Most engagements silently fail here, not at ship.
+
+Counter it:
+- Ship one visible artifact per week, even if discovery isn't done. A terrain map, a risk register, a stakeholder signal update - something the sponsor can point to.
+- Proactive status update at end of week 2 - explicitly name what discovery revealed that wasn't in the brief. This resets expectations with evidence.
+- If still in discovery at week 3: the conversation with the sponsor about scope or timeline reset is overdue. Don't wait for them to ask.
+
+## Principles
+
+- Trust is earned in small moves, lost in one. Never skip the ladder.
+- The first-week plays are specific and deliberate - not "be helpful."
+- AI policy: ask, never assume. Prohibited until confirmed.
+- Mistakes happen; hiding them doesn't. Own it in the first hour.
+- The FDE who makes the internal team look right earns trust faster than the FDE who ships the most code.
+- Weeks 2-4 are where engagements silently die. Ship visible artifacts weekly to survive the valley.

package/skills/earn-trust/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/evaluate/.fde-generated.json

@@ -10,7 +10,7 @@
     "references/qa.md": "d8f58e6d36436469a58aeb1107037f3e27fa81ff5b82d0e4df3c23eeadaf683c",
     "references/review.md": "63a007f78288089cc84cccc72647e8ce6721b7efa0f4f8d6774c0f0af594749d",
     "references/ship.md": "8cdcb2d4d6eb57e0adf3f1996bc02ae66920852ca304d2afd778fa483b7e969a",
-    "references/task-context.md": "8ec90708522e512a50a57ab2a377a7472e93bae169c6f075a93fa603ce2ad780",
+    "references/task-context.md": "73eea2d7f164fac3226599e5be26ae4e79dcf69e0d24428dd12d623861410490",
     "references/verification.md": "d453c075b849437375338fd23782ca7fe6d427b05137a2b10fc2f724aaf7f8a9"
   }
 }

package/skills/evaluate/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/fde/SKILL.md

@@ -126,7 +126,7 @@ Direct. Their words. No "Certainly." Playback 2-4 lines, then act. One question
 
 New embed: sprint / standard / programme changes depth, not which skills exist. Before first code: safe place to break things, plus AI-code policy. Before go-live: who needs to know, what's the rollback. Before a sponsor artifact: as-is or gut-check first.
 
-Muddy signal: name it ("discover or rescue - leaning X"). Never a phase-picker interview. Default: land if new, audit if takeover.
+Muddy signal: name it ("discover or rescue - leaning X"). Never a phase-picker interview. Default: brief if new, audit if takeover.
 
 ## Routing - 6 stages
 
@@ -136,11 +136,11 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
 
 | You hear | Skill | Reference |
 |----------|-------|-----------|
-| Engage, onboarding, starting fresh, new customer, first meeting, just got the brief, set product strategy, define success metrics, scope the brief | land | `references/land.md` |
+| Engage, onboarding, starting fresh, new customer, first meeting, just got the brief, set product strategy, define success metrics, scope the brief | brief | `references/land.md` |
 | Taking over, previous consultant left, joining mid-project | audit | `references/audit.md` |
 | Need to understand who matters, who decides, map decision rights, who blocks quietly | who-decides | `references/who-decides.md` |
 | Need to earn access, navigate AI policy, build credibility | earn-trust | `references/earn-trust.md` |
-| "Also can you…", scope expanding, timeline unchanged, hold scope, scope the brief after kickoff | hold-scope | `references/hold-scope.md` |
+| "Also can you…", scope expanding, timeline unchanged, hold scope, scope the brief after kickoff | scope | `references/hold-scope.md` |
 
 ### Discover
 
@@ -157,8 +157,8 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
 |----------|-------|-----------|
 | Align, break this down, what order, sequence the delivery, align the plan | plan | `references/plan.md` |
 | Sponsor needs justification, need to defend budget or timeline, build the business case | business-case | `references/business-case.md` |
-| Significant decision, multiple approaches, "what should we do?", generate solutions, generate options, not the playbook, from the surviving facts | three-options | `references/three-options.md` |
-| 20 things are "urgent," need to pick the 3 that matter, prioritize three | pick-three | `references/pick-three.md` |
+| Significant decision, multiple approaches, "what should we do?", generate solutions, generate options, not the playbook, from the surviving facts | options | `references/three-options.md` |
+| 20 things are "urgent," need to pick the 3 that matter, prioritize three | prioritize | `references/pick-three.md` |
 
 ### Ship
 
@@ -172,6 +172,7 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
 | Exercise the customer journey, browser acceptance, functional QA | qa | `references/qa.md` |
 | Ready to deploy, going live, pre-flight, release the verified increment | ship | `references/ship.md` |
 | Review this change, review the pull request, is it safe, does it match what we agreed | review | `references/review.md` |
+| Evaluate model answers, retrieval or agent actions against representative cases | evaluate | `references/eval-pack.md` |
 | Diff grew / scope creep in the PR / "did we only build what we said" / KEEP JUSTIFY SPLIT DROP | review (+ ship if going live) | `references/review.md` Stage 1 · `references/ship.md` Intent vs diff |
 | Wrap the session / share the thinking / catch teammates up / before I open the PR | (memory contract - session digest) | SKILL.md **Session digest** - write TL;DR + decisions/why into `.fde/`; no transcript sync |
 | "We can always revert" - need to actually test the escape route, rehearse rollback | rollback | `references/rollback.md` |
@@ -184,7 +185,7 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
 | Demo coming up, show-and-tell, exec walkthrough, prepare the demo | demo-prep | `references/demo-prep.md` |
 | Just out of a meeting, raw notes, "they said…", "debrief", user interviews, workshop notes, capture the meeting | debrief | the debrief verb (above) + `references/debrief.md` |
 | Make sure we're up to date, pull what's relevant, fetch from Granola/Slack/Gmail/transcript | ingest | `references/ingest.md` (capability check → stage → propose → confirm → apply) |
-| Connect a new MCP / connect Granola Slack or Notion / what can you pull | connect | `references/connect.md` (+ `mcp/recipes/`) |
+| Connect a new MCP / connect Granola Slack or Notion / what can you pull | connect | `references/connect.md` (+ `references/source-setup.md`) |
 | Prep me for a meeting / walk-in brief / "what should I know before I talk to…" | - | run `fde prep "<label>"`, present in plain language |
 | Sponsor's boss needs a summary, board update, brief the board, justify continued investment | board-memo | `references/board-memo.md` |
 | Status across all my customers, view the portfolio | dashboard | `references/dashboard.md` |
@@ -194,9 +195,9 @@ Work names (engage, diagnose, align, deliver, realize, transfer) are the same ma
 | You hear | Skill | Reference |
 |----------|-------|-----------|
 | Juggling 2+ customers, losing track, context-switching, switch engagements | switch-clients | `references/switch-clients.md` |
-| Transfer, wrapping up, handoff, making yourself replaceable, transfer operations | close | `references/close.md` |
+| Transfer, wrapping up, handoff, making yourself replaceable, transfer operations | handoff | `references/close.md` |
 | Engagement ending, team needs to operate without you, write the runbook | runbook | `references/runbook.md` |
-| Something worked well and will apply to future engagements, encode the pattern | encode-pattern | `references/encode-pattern.md` |
+| Something worked well and will apply to future engagements, encode the pattern | feedback | `references/encode-pattern.md` |
 | "Red-team this," "stress-test my plan," poke holes, challenge the plan, what am I missing | red-team | `references/red-team.md` |
 | "What did we agree about X?", scope dispute, receipts | - | run `fde receipts <term>`, answer with dates |
 

package/skills/fde/references/connect.md

@@ -1,34 +1,24 @@
 # connect - Connect a source
 
-**Enter when:** the FDE says "I want to connect a new MCP", "connect Granola / Slack / Notion", "how do I pull from …", or a pull request fails because no source tools exist.
+**Enter when:** the user asks to connect a notes, chat or document source, or an expected source cannot be read.
 
-**Read first:** `references/ingest.md` (sink contract). Recipes: `mcp/recipes/` (file, granola, slack, notion).
-
-**Who runs setup:** you guide; the **host** (Cursor/Claude) must save MCP config. You cannot silently install servers into the host.
-
-## Honest contract
-
-- **Daily work does not need a source MCP.** Paste notes → debrief. File on disk → `fde ingest`.
-- **Connect means a source**, not FDEOps. Granola/Slack/Notion credentials stay with that MCP. FDEOps never pushes, never ambient-syncs, never stores their tokens.
-- **Sink is the CLI in this bound workspace** (`fde ingest`). `fdeops-ingest` MCP is optional. If you use it, pass `engagement` as the `.fde/` path from `fde resume --bind` (MCP servers often do not inherit the workspace bind).
-- Never invent that Granola/Slack is available if tools are missing. Never auto-apply to `.fde/`.
+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. **Ask one question** - which source? (`file` / `granola` / `slack` / `notion` / other). If "other", ask for the MCP they intend to use. If they just want paste → send them to debrief and stop.
-2. **Capability check (current session)** - list MCP tools you can actually call:
-   - Sink: `fde ingest` CLI (preferred) and/or `ingest_stage`
-   - Source: anything that can **fetch** that system's content (not post)
-   - Say clearly: *available now* vs *needs config*.
-3. **Emit config for the source only** - open `mcp/recipes/<source>.md`. Fill placeholders from *that product's* docs. Tell them to paste secrets into host env - never into `.fde/`.
-4. **Tell them where to paste** - Cursor MCP settings / `mcp.json`. Claude Code: their MCP config. Save → reload MCP / restart session.
-5. **Verify** - after reload: re-run capability check. If source tools appear, offer a **test pull** staged to `.inbox/` only. Stop before apply unless they ask to propose.
-6. **Handoff phrase** - e.g. `@fde pull today's Acme Granola into the fieldbook`.
+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.
 
-## If they only want paste / files
+## Checkpoint
 
-Do not add MCP. Use debrief or [mcp/recipes/file.md](../../../mcp/recipes/file.md).
+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.
 
-## Checkpoint
+## Principles
 
-Before ending connect: (1) they know paste still works, (2) source reachable or honest gap, (3) they know the pull phrase. Do not write `.fde/` during connect.
+- 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/fde/references/debrief.md

@@ -2,6 +2,8 @@
 
 **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.

package/skills/fde/references/ingest.md

@@ -2,7 +2,9 @@
 
 **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. Recipes: `mcp/recipes/` (file, granola, slack, notion).
+**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.
 
@@ -60,7 +62,7 @@ Carry an actual `[source: ...]` locator on each consequential fact. Preserve ups
 
 ## 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`. Copy-paste recipes: `mcp/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
 

package/skills/fde/references/plan.md

@@ -6,7 +6,7 @@
 
 **Read first:** `reality.md`, `success.md`, `terrain.md`, `stakeholders.md`. Load `business-case.md` if poc produced one. Not the full folder.
 
-**On an initialized engagement, before a new delivery plan or material scope change:** run `fde doctor --ready`. For standalone planning, check the supplied outcome, scope, acceptance and authority directly; do not initialize records to run this validator. Missing binary success or a named customer-side signer blocks progression: review the proposed acceptance check and authority with the FDE first. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer, acceptance criteria, and engineering plan; record verification without reopening settled decisions.
+**On an initialized engagement, before a new delivery plan or material scope change:** run `fde doctor --ready`. For standalone planning, check the supplied outcome, scope, acceptance and authority directly; do not initialize records to run this validator. Missing acceptance criteria or authority blocks the affected implementation commitment, not a provisional plan. Draft proposed checks and next steps, mark them pending, and ask only what changes the next action. Use a test/input and observable pass/fail under **Done when:** or **Acceptance check:**. A number, role, or successful demo alone is insufficient. Do not invent missing facts to pass lint. Routine reversible fixes within confirmed scope reuse the existing signer, acceptance criteria, and engineering plan; record verification without reopening settled decisions.
 
 ## Validation gate (confirm understanding, clarify where it elevates)
 
@@ -17,8 +17,8 @@ Before planning, state what you're working from in 2-3 lines:
 Then check - probe ONLY if it prevents a bad plan:
 
 1. **Success is measurable.** If "done" is vague ("make it better") → rephrase it: "I'm reading success as: [specific measurable outcome]. That the target?"
-2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Planning against reality unless you say otherwise."
-3. **Out-of-scope exists.** If missing → one line: "Nothing's marked out-of-scope yet. That means every new request is implicitly in. Worth defining now or after the first plan draft?"
+2. **Reality matches the brief.** If discovery contradicted the brief → name it: "Discovery found [X] but the brief says [Y]. Here is the proposed adjustment; it remains unagreed until confirmed."
+3. **Out-of-scope exists.** If missing → one line: "I will keep this draft within the supplied request and mark proposed exclusions for confirmation."
 
 State your read, let the FDE correct, then plan.
 
@@ -42,19 +42,19 @@ An FDE plan is not a sprint backlog. The technical sequence is the easy part. Th
 
 **6. Stakeholder touchpoints every 2-3 tasks.** "Show progress to <name from stakeholders.md>." Not ceremony: a customer who sees small wins stays bought in; silence gets filled with doubt.
 
-**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Cap **Now** at 3 PRs (same discipline as pick-three).
+**7. End with a kill list.** Every plan names what you will **not** do this phase. If everything is "later," you have no plan - you have a wish list. Keep **Now** small enough to review and act on; split by independently verifiable outcomes.
 
 **Acceptance criteria gate:** no task moves to build without written happy-path AND unhappy-path criteria. Can't write them = the task isn't understood; the open question goes to the customer **before** the task starts. Vague criteria surface later as scope creep and rework.
 
 ## Artifact
 
-The plan goes to **`decisions.md`** - always. Build reads the plan from `decisions.md`; anywhere else and the build starts blind.
+For standalone planning, return the requested draft or save to the authorized project document. In a bound engagement, propose the plan for **`decisions.md`** under its confirmation rules, or link the existing approved plan; do not duplicate it.
 
 A plan is **not done** until all four blocks exist:
 
 ```markdown
 ## Plan - <date>
-### Now (max 3)
+### Now
 Task N: <outcome, not activity>
 Delivers: <what someone can see/test>
 Accepts: <happy path> / <unhappy path>

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.