@questionbase/deskfree 0.3.0-alpha.21 → 0.3.0-alpha.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@questionbase/deskfree",
-  "version": "0.3.0-alpha.21",
+  "version": "0.3.0-alpha.22",
   "description": "OpenClaw channel plugin for DeskFree — turns DeskFree into a messaging platform for OpenClaw AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/deskfree/SKILL.md

@@ -2,14 +2,14 @@
 name: deskfree
 description: >
   DeskFree task management and human-AI collaboration workflows.
-  Use when: creating tasks, managing work items, updating deliverables,
+  Use when: creating tasks, managing work items, updating files,
   communicating with humans through DeskFree, checking workspace state,
   handling task lifecycle (start → work → complete → review),
   evaluating completed tasks, updating ways of working, managing initiatives.
   Do NOT use for: general project management advice without DeskFree tools,
   OpenClaw configuration or gateway setup, non-DeskFree platforms (Jira, Asana, etc.),
   direct file/code operations (use standard tools for those, create DeskFree tasks for tracking).
-version: 7.0.0
+version: 8.0.0
 metadata: { 'openclaw': { 'emoji': '🏠' } }
 ---
 
@@ -42,7 +42,7 @@ suggest_tasks → [human approves] → bot → [start_task] → bot (is_working)
                                                               + initiative updated (if task has initiative_id)
 ```
 
-- `complete_task` outcome `done` = work complete for review
+- `complete_task` outcome `done` = work complete (summary required)
 - `complete_task` outcome `blocked` = need human input (send message FIRST explaining why)
 - Both outcomes move to `human` — the human triages from there
 - When human approves (`done`), a pending evaluation is created for ways-of-working update
@@ -50,42 +50,56 @@ suggest_tasks → [human approves] → bot → [start_task] → bot (is_working)
 ### The Work Loop
 
 ```
-1. Check state     → deskfree_state — see tasks, active initiatives, pending evaluations
-2. Suggest tasks   → deskfree_suggest_tasks — propose work + optional initiative suggestions
-3. Claim a task    → deskfree_start_task — read instructions + parent context
-4. Do the work     → deskfree_update_deliverable — build incrementally
-5. Suggest follow-ups → if work reveals more to do, suggest them (link to initiative)
-6. Complete        → deskfree_complete_and_suggest (or deskfree_complete_task) — deliverable required
+1. Check state     → deskfree_state — see tasks, active initiatives, files, pending evaluations
+2. Suggest tasks   → deskfree_suggest_tasks — propose work + optional initiative + file suggestions
+3. Claim a task    → deskfree_start_task — read instructions + parent context + fileContext
+4. Do the work     → deskfree_update_file — build linked file incrementally
+5. Suggest follow-ups → if work reveals more to do, suggest them via deskfree_suggest_tasks (link to initiative)
+6. Complete        → deskfree_complete_task — summary required for "done"
 7. Evaluate        → if approved tasks have pending WoW evaluation (update globalWoW + initiative)
 ```
 
 ### Three Rules That Break Everything If Ignored
 
 1. **Always suggest first.** Use `deskfree_suggest_tasks` before starting ANY work. Tasks go through human approval. No exceptions.
-2. **Always check state first.** Call `deskfree_state` before suggesting tasks. Prevents duplicates, shows active initiatives.
-3. **Always complete tasks.** Never leave a task in `bot` (is_working=true). End with `deskfree_complete_and_suggest` or `deskfree_complete_task` — outcome `done` or `blocked`.
+2. **Always check state first.** Call `deskfree_state` before suggesting tasks. Prevents duplicates, shows active initiatives and files.
+3. **Always complete tasks.** Never leave a task in `bot` (is_working=true). End with `deskfree_complete_task` — outcome `done` or `blocked`.
 
 ### Writing Great Instructions
 
 Write instructions as if briefing a contractor who has never seen the codebase. Include:
 - **What to do** — specific, actionable steps
-- **Why** — referencing parent findings or deliverable when applicable
+- **Why** — referencing parent findings or file content when applicable
 - **What "done" looks like** — clear acceptance criteria
 - **Known constraints** — gotchas, dependencies, things to avoid
 
-### Deliverable Requirements
+### File-Based Work Output
 
-**MUST update deliverable before completing with outcome "done".** Minimum: structured summary of what was found/done, decisions made, and recommendations. An empty or placeholder deliverable will be rejected.
+**Work that produces persistent documents should use files.** A file persists beyond the task — it becomes the lasting artifact of your work.
+
+**When to use files:**
+- Writing specs, runbooks, reports, documentation
+- Any output a human will reference after the task closes
+- Output that follow-up tasks will build on
+
+**How to link files to tasks:**
+- Use `newFile` in `deskfree_suggest_tasks` to pre-create a file when you know the task will produce one
+- Use `fileId` to link an existing file to a new task
+- When claiming a task with a linked file, its current content is in `fileContext` — read it before starting work
+
+**Completing a task:**
+- Provide a clear `summary` of what was accomplished (required for outcome `done`)
+- If the task updated a file, mention the file name/ID in the summary
 
 ### Suggesting Follow-ups
 
 When completing, always consider: does this work reveal follow-up tasks? If yes, suggest them. Your suggestions are strongest at this moment because you have full context.
 
-Use `deskfree_complete_and_suggest` to complete and suggest in one atomic call. Estimate token cost per suggestion — consider how many files to read, how much reasoning, how much output.
+Call `deskfree_suggest_tasks` before or after completing — pass `parentTaskId` to link follow-ups to the current task. Estimate token cost per suggestion — consider how many files to read, how much reasoning, how much output.
 
 ### Building the Chain
 
-You're not just doing tasks — you're building a chain. The instructions you write become someone else's brief. The deliverable you produce becomes someone else's context. Write both with care.
+You're not just doing tasks — you're building a chain. The instructions you write become someone else's brief. The files you produce become someone else's context. Write both with care.
 
 ### Auto-Threading
 
@@ -95,6 +109,67 @@ The task sidebar is your human's window into your work — every message appears
 
 ---
 
+## Working with Files
+
+Files are persistent documents owned by a bot that live across tasks.
+
+```
+deskfree_state() → shows files: [{fileId, name, description, version, updatedAt}, ...]
+
+deskfree_start_task(taskId) → if task.fileId, returns fileContext: {
+  fileId, name, description, content, contentFormat, version
+}
+```
+
+### Creating Files
+
+```javascript
+// Option 1: Pre-create when suggesting a task
+deskfree_suggest_tasks({
+  suggestions: [{
+    title: "Write API documentation",
+    instructions: "...",
+    newFile: {
+      name: "API Reference",
+      description: "Full API reference documentation for v2 endpoints"
+    }
+  }]
+})
+// → file is created and linked to the task
+
+// Option 2: Create a file directly during work
+deskfree_create_file({
+  name: "Deployment Runbook",
+  description: "Step-by-step deployment guide",
+  content: "# Deployment Runbook\n\n...",
+  contentFormat: "markdown"
+})
+```
+
+### Updating Files
+
+```javascript
+// Always send the full current content — each call replaces the previous version
+deskfree_update_file({
+  fileId: "F_abc123",
+  content: "# Full document...",
+  contentFormat: "markdown"  // or "html"
+})
+```
+
+**Build incrementally** — update the file early and often. A half-complete file is infinitely better than none if you're interrupted.
+
+### File Format Choice
+
+| Format | Use when |
+|---|---|
+| `markdown` (default) | Text reports, specs, documentation, analysis, code snippets |
+| `html` | Rich web content: dashboards, styled reports, interactive tables |
+
+HTML files are rendered in a **sandboxed iframe**. Use `format="html"` when layout and styling matter for the human's review.
+
+---
+
 ## Initiatives — Long-Lived Areas of Focus
 
 Initiatives answer **"what are we working on and why"** while Ways of Working answers **"how do we work."**
@@ -105,6 +180,8 @@ Initiatives answer **"what are we working on and why"** while Ways of Working an
 | **Initiative Content** | A versioned markdown doc — current state, approach, next priorities |
 | **Task → Initiative link** | Set `initiativeId` on suggestions to link tasks to an initiative |
 
+**Default initiative:** Every bot has a "General" initiative for uncategorized work. Tasks without an explicit `initiativeId` are automatically linked to it.
+
 ### When to Propose a New Initiative
 
 ```
@@ -113,7 +190,7 @@ On every suggest_tasks call, ask yourself:
 "Does an active initiative exist that this work belongs to?"
 → Yes: set initiativeId on the relevant suggestions
 → No, but this is part of a bigger theme: add an initiativeSuggestion
-→ No, and it's a one-off task: no initiative needed
+→ No, and it's a one-off task: no initiative needed (defaults to General)
 ```
 
 ### Initiative Suggestion Flow
@@ -178,7 +255,7 @@ When a human approves a task, it enters `pendingEvaluations` in state.get. Evalu
 1. deskfree_claim_evaluation(taskId)
    → returns: task + messages + waysOfWorking + initiative (if task has initiative_id)
 
-2. Read the task deliverable and messages thoroughly
+2. Review the task summary, messages, and any file output
 
 3. Ask yourself:
    "Did I learn something about HOW we work that applies everywhere?"
@@ -217,7 +294,7 @@ When a human approves a task, it enters `pendingEvaluations` in state.get. Evalu
 Task "Audit auth endpoints" (linked to "Auth Hardening" initiative) is approved.
 
 claim_evaluation → returns:
-  task (with deliverable showing 3 critical issues found)
+  task (with summary: "Found 3 critical issues: session fixation, weak CSRF, no rate limiting")
   waysOfWorking: "..."
   initiative: { id: "init_abc", title: "Auth Hardening", content: "No audit done yet." }
 
@@ -248,21 +325,23 @@ submit_evaluation({
 - [ ] Called `deskfree_state` — confirmed it returned data (not empty/error)
 - [ ] Read `waysOfWorking` if present — apply established patterns
 - [ ] Read `initiatives` if present — check for active initiatives this work belongs to
+- [ ] Checked `files` list — know what persistent files already exist
 - [ ] Checked for existing tasks that match intent — no duplicates
-- [ ] Suggested a task via `deskfree_suggest_tasks` — with `initiativeId` if linking to existing initiative, or `initiativeSuggestions` if proposing new one
+- [ ] Suggested a task via `deskfree_suggest_tasks` — with `initiativeId` if linking to existing initiative, or `initiativeSuggestions` if proposing new one, and `newFile` if task will produce a document
 - [ ] Once approved: called `deskfree_start_task` — confirmed task moved to `bot` (is_working=true)
+- [ ] If task has `fileContext` — read the existing file content before starting work
 
 ### Mid-Work
 
-- [ ] Deliverable started immediately after starting task (not waiting until end)
-- [ ] `deskfree_update_deliverable` succeeded (no error response)
+- [ ] File updated immediately after starting task (not waiting until end)
+- [ ] `deskfree_update_file` succeeded (no error response)
 - [ ] If blocked: sent message explaining WHY before calling `complete_task` with `blocked`
 
 ### Pre-Completion
 
-- [ ] Deliverable is non-empty and meaningful (not just headers/placeholders)
-- [ ] Deliverable is well-structured markdown that stands alone
-- [ ] Called `deskfree_complete_task` — confirmed task moved to `human`
+- [ ] File content is non-empty and meaningful (if task produces a file)
+- [ ] File is well-structured and stands alone as a document
+- [ ] Called `deskfree_complete_task` with a clear `summary` — confirmed task moved to `human`
 - [ ] If sub-agent: terminated after completion (one task per sub-agent)
 
 ### Heartbeat Evaluation Check
@@ -276,21 +355,24 @@ submit_evaluation({
 ### Orchestrator Flow (main session)
 
 ```
-1. deskfree_state                  → assess workspace + read ways of working + check active initiatives
-2. deskfree_suggest_tasks          → suggest tasks (with estimatedTokens, initiativeId, initiativeSuggestions)
-3. deskfree_start_task             → claim approved task (returns full context + parent context)
-4. deskfree_update_deliverable     → build incrementally as you work
-5. deskfree_complete_and_suggest   → complete + suggest follow-ups (or deskfree_complete_task if no follow-ups)
+1. deskfree_state                  → assess workspace + read ways of working + check active initiatives + check files
+2. deskfree_suggest_tasks          → suggest tasks (with estimatedTokens, initiativeId, initiativeSuggestions, newFile)
+3. deskfree_start_task             → claim approved task (returns full context + parent context + fileContext)
+4. deskfree_update_file            → build linked file incrementally as you work
+5. deskfree_suggest_tasks          → suggest follow-ups if work reveals more (parentTaskId to link)
+6. deskfree_complete_task          → complete with outcome done (+ summary) or blocked
 ```
 
 ### Sub-Agent Flow (recommended for tasks > 5 min)
 
 ```
 Orchestrator: deskfree_suggest_tasks → (human approves) → deskfree_start_task → spawn sub-agent with full task context
-Sub-agent:    deskfree_update_deliverable (incrementally) → deskfree_complete_task → terminate
+Sub-agent:    deskfree_update_file (incrementally) → deskfree_suggest_tasks (follow-ups if needed) → deskfree_complete_task (+ summary) → terminate
 ```
 
-Sub-agents have **4 tools:** `deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message` (also supports task suggestions), `deskfree_submit_evaluation`. They cannot suggest tasks, read workspace state, or claim evaluations.
+Sub-agents have **7 tools:** `deskfree_update_file`, `deskfree_create_file`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_suggest_tasks`, `deskfree_claim_evaluation`, `deskfree_submit_evaluation`. Workers have workspace context for awareness — focus on your assigned task and use context to avoid duplicate suggestions.
+
+**Worker pattern — after submitting evaluation:** reflect on what you learned and call `deskfree_suggest_tasks` for follow-up opportunities that emerged from the evaluation.
 
 ### When to Use Main vs Sub-Agent
 
@@ -303,6 +385,50 @@ Sub-agents have **4 tools:** `deskfree_update_deliverable`, `deskfree_complete_t
 
 ---
 
+## Recurrence — Natural Language + scheduledFor
+
+**Recurrence is handled through task instructions, NOT through special fields.** DeskFree uses a simple suggest → complete → suggest cycle for recurring work.
+
+### How Recurrence Works
+
+1. **Document the pattern** in task instructions using natural language:
+   - "This task recurs weekly on Mondays. When completing, suggest the next occurrence with scheduledFor set to next Monday."
+   - "Monthly report — recurs on the 1st of each month. Schedule next occurrence for first day of next month."
+
+2. **Set the first occurrence** using `scheduledFor` in your suggestion:
+   ```javascript
+   deskfree_suggest_tasks({
+     suggestions: [{
+       title: "Weekly team sync prep",
+       instructions: "Prepare agenda for Monday team meeting. This task recurs weekly on Mondays. When completing, suggest the next occurrence with scheduledFor set to next Monday at 9 AM.",
+       scheduledFor: "2026-03-03T14:00:00Z" // Next Monday 9 AM EST
+     }]
+   })
+   ```
+
+3. **Propagate on completion** — when you complete a recurring task, read the instructions and suggest the next occurrence:
+   ```javascript
+   // After completing the task:
+   deskfree_suggest_tasks({
+     suggestions: [{
+       title: "Weekly team sync prep",
+       instructions: "Prepare agenda for Monday team meeting. This task recurs weekly on Mondays. When completing, suggest the next occurrence with scheduledFor set to next Monday at 9 AM.",
+       scheduledFor: "2026-03-10T14:00:00Z" // Following Monday
+     }],
+     parentTaskId: "current-task-id"
+   })
+   ```
+
+### Key Points
+
+- **No special recurrence fields** — it's just natural language in instructions + `scheduledFor`
+- **You are responsible** for reading the recurrence pattern and creating the next occurrence
+- **Use scheduledFor** to control when the task becomes available
+- **Include the recurrence instructions** verbatim in follow-up suggestions so the pattern continues
+- **Be precise with dates** — calculate the next occurrence based on the documented pattern
+
+---
+
 ## Messaging
 
 **Normal replies:** Just respond — the channel handles routing automatically. No tool needed.
@@ -320,20 +446,21 @@ Sub-agents have **4 tools:** `deskfree_update_deliverable`, `deskfree_complete_t
 
 ### Heartbeat / Proactive Check
 
-1. `deskfree_state` → get workspace snapshot + check `waysOfWorking` + `initiatives` + `pendingEvaluations`
+1. `deskfree_state` → get workspace snapshot + check `waysOfWorking` + `initiatives` + `files` + `pendingEvaluations`
 2. `pendingEvaluations`? → `deskfree_claim_evaluation` → `deskfree_submit_evaluation` (with globalWoW + initiative outputs)
 3. `bot` tasks? → `deskfree_start_task` + spawn sub-agents
 4. `bot` (is_working=true) with no active sub-agent? → Complete as blocked or resume
 
 ### Human Gives You Work
 
-1. `deskfree_state` → check existing tasks + read ways of working + check active initiatives
+1. `deskfree_state` → check existing tasks + read ways of working + check active initiatives + check files
 2. Does this work belong to an active initiative? → set `initiativeId` on suggestions
    OR is this starting a new area of focus? → add `initiativeSuggestions`
-3. `deskfree_suggest_tasks` → suggest with clear title + instructions
-4. [human approves] → `deskfree_start_task` → claim it
-5. Work → `deskfree_update_deliverable` incrementally
-6. `deskfree_complete_task` → outcome `done` or `blocked`
+3. Will the task produce a persistent document? → add `newFile` to the suggestion
+4. `deskfree_suggest_tasks` → suggest with clear title + instructions
+5. [human approves] → `deskfree_start_task` → claim it + read fileContext if present
+6. Work → `deskfree_update_file` incrementally
+7. `deskfree_complete_task` → outcome `done` (with summary) or `blocked`
 
 ---
 
@@ -341,50 +468,41 @@ Sub-agents have **4 tools:** `deskfree_update_deliverable`, `deskfree_complete_t
 
 > **Full parameter details:** See `references/tools.md`
 
-### Orchestrator (10 tools)
+### Orchestrator (9 tools)
 
 | Tool | What it does |
 |---|---|
-| `deskfree_state` | Full workspace snapshot — tasks, recently done, ways of working, active initiatives, pending evaluations |
-| `deskfree_suggest_tasks` | Suggest tasks for human approval (with estimatedTokens, initiativeId, initiativeSuggestions) |
-| `deskfree_start_task` | Claim task → `bot` (is_working=true), returns full context + parent context |
-| `deskfree_update_deliverable` | Build deliverable markdown incrementally |
-| `deskfree_complete_task` | Mark done or blocked → `human` |
-| `deskfree_complete_and_suggest` | Complete current task + suggest follow-ups in one atomic call |
-| `deskfree_send_message` | Message in task thread |
+| `deskfree_state` | Full workspace snapshot — tasks, recently done, ways of working, active initiatives, files, pending evaluations |
+| `deskfree_suggest_tasks` | Suggest tasks for human approval (with estimatedTokens, initiativeId, initiativeSuggestions, newFile, fileId) |
+| `deskfree_start_task` | Claim task → `bot` (is_working=true), returns full context + parent context + fileContext |
+| `deskfree_update_file` | Update a linked file's content incrementally |
+| `deskfree_create_file` | Create a new persistent file |
+| `deskfree_complete_task` | Mark done (summary required) or blocked → `human` |
+| `deskfree_send_message` | Message in task thread (content required) |
 | `deskfree_claim_evaluation` | Claim a pending evaluation — returns task, messages, globalWoW, and initiative (if applicable) |
 | `deskfree_submit_evaluation` | Submit evaluation with dual output: globalWoW + initiative (each independently updatable) |
 
-### Worker (4 tools — sub-agents only)
-
-`deskfree_update_deliverable`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_submit_evaluation`
-
----
-
-## Deliverable Best Practices
+### Worker (7 tools — sub-agents only)
 
-### Choosing a format
+`deskfree_update_file`, `deskfree_create_file`, `deskfree_complete_task`, `deskfree_send_message`, `deskfree_suggest_tasks`, `deskfree_claim_evaluation`, `deskfree_submit_evaluation`
 
-`deskfree_update_deliverable` accepts an optional `format` parameter:
+Workers receive workspace context at spawn time — use it to understand what else is happening, avoid duplicate suggestions, and link follow-ups to existing initiatives.
 
-| Format | Use when |
-|---|---|
-| `markdown` (default) | Text reports, analysis, documentation, code — anything prose-based |
-| `html` | Rich web content: dashboards, styled reports, interactive tables, data visualizations |
+---
 
-HTML deliverables are rendered in a **sandboxed iframe** (no access to parent page). Use `format="html"` when layout and styling matter for the human's review. Use `format="markdown"` for everything else.
+## File Best Practices
 
-### Markdown deliverables
+### Markdown files
 
 Structure as **standalone markdown documents:**
 
 ```markdown
-# Task Title
+# Document Title
 
 ## Summary
-Brief overview of what was accomplished.
+Brief overview of what this document covers.
 
-## Key Findings / Results
+## Key Findings / Content
 - Main points with supporting detail
 
 ## Details
@@ -394,7 +512,7 @@ Detailed analysis, implementation notes, etc.
 - Follow-up actions, outstanding questions
 ```
 
-### HTML deliverables
+### HTML files
 
 Pass a complete, self-contained HTML document (or fragment — a wrapper `<html>` is injected automatically):
 
@@ -406,7 +524,7 @@ Pass a complete, self-contained HTML document (or fragment — a wrapper `<html>
 </table>
 ```
 
-**Build incrementally** — start with outline immediately after `deskfree_start_task`, fill sections as you go, polish before completing. A half-complete deliverable is infinitely better than none.
+**Build incrementally** — start with outline immediately after `deskfree_start_task`, fill sections as you go, polish before completing. A half-complete file is infinitely better than none.
 
 ---
 
@@ -419,7 +537,8 @@ Pass a complete, self-contained HTML document (or fragment — a wrapper `<html>
 | 404 on `deskfree_complete_task` | Task not `bot` (is_working=true) | Already completed or released. Check state. |
 | 409 on `deskfree_start_task` | Race condition — another bot claimed it | Call `deskfree_state`, pick a different task. |
 | 401 Unauthorized | Bot token invalid or expired | Check channel configuration. Do not retry. |
-| `deskfree_update_deliverable` fails | Task not in `bot` (is_working=true) or network error | Verify task state with `deskfree_state`. If task was released, re-claim or abort. |
+| `deskfree_update_file` fails | File not found or network error | Verify fileId with `deskfree_state`. If file was deleted, create a new one. |
+| 422 on `deskfree_complete_task` | Missing required `summary` for outcome `done` | Add a meaningful summary of what was accomplished. |
 | `deskfree_claim_evaluation` returns null | Already claimed by another process | No action needed. Move to next pending evaluation. |
 | Sub-agent spawn fails | Resource limits, config error | Complete task as `blocked` with explanation. Do not leave in `bot` (is_working=true). |
 | WebSocket disconnected | Network issue | Plugin auto-reconnects with backoff. Messages fall back to HTTP polling. No action needed. |
@@ -428,7 +547,7 @@ Pass a complete, self-contained HTML document (or fragment — a wrapper `<html>
 
 If anything goes wrong mid-task:
 1. Send a message explaining what happened (`deskfree_send_message`)
-2. Save whatever partial deliverable you have (`deskfree_update_deliverable`)
+2. Save whatever partial file content you have (`deskfree_update_file`)
 3. Complete as `blocked` (`deskfree_complete_task` with outcome `blocked`)
 4. **Never leave a task stranded in `bot` (is_working=true)**
 
@@ -437,10 +556,10 @@ If anything goes wrong mid-task:
 | Scenario | Guidance |
 |---|---|
 | **Concurrent task access** | If multiple bots try to claim the same task, one will get 409 Conflict. The winner proceeds, losers should call `deskfree_state` and pick different tasks. |
-| **Long-running operations** | For tasks >10 minutes, send periodic progress updates via `deskfree_send_message` so humans know you're still working. Update deliverable incrementally. |
-| **Partial deliverable recovery** | If interrupted mid-work, `deskfree_start_task` returns the current deliverable content. Resume from where you left off, don't start over. |
-| **Network timeouts during updates** | If `deskfree_update_deliverable` times out, retry once. If it fails again, complete as `blocked` with the timeout explanation. |
-| **Empty or corrupt deliverables** | Always validate deliverable content before calling `deskfree_update_deliverable`. Minimum viable content is better than empty/corrupted content. |
+| **Long-running operations** | For tasks >10 minutes, send periodic progress updates via `deskfree_send_message` so humans know you're still working. Update file incrementally. |
+| **Partial file recovery** | If interrupted mid-work, `deskfree_start_task` returns the current file content in `fileContext`. Resume from where you left off, don't start over. |
+| **Network timeouts during updates** | If `deskfree_update_file` times out, retry once. If it fails again, complete as `blocked` with the timeout explanation. |
+| **Empty or corrupt file content** | Always validate file content before calling `deskfree_update_file`. Minimum viable content is better than empty/corrupted content. |
 | **Sub-agent coordination** | Only one sub-agent per task. If a sub-agent fails to start, the main session should resume the task directly. Don't spawn multiple sub-agents for the same task. |
 | **Evaluation claim conflicts** | `deskfree_claim_evaluation` returns `null` if another process claimed it first. This is normal - move to the next pending evaluation or complete your heartbeat. |
 | **Ways of working too large** | If ways of working content becomes very large (>50KB), consider archiving old sections. Focus updates on recent patterns and current best practices. |
@@ -457,12 +576,12 @@ If anything goes wrong mid-task:
 - **Solution**: Pass explicit `taskId` to `deskfree_send_message`
 - **Debug**: Check that `deskfree_start_task` was called and returned successfully
 
-#### Deliverable Updates Failing
+#### File Updates Failing
 - **Common causes**:
-  - Task was released by another process → call `deskfree_state` to verify task status
-  - Deliverable content is malformed (invalid markdown, control characters)
+  - File ID is wrong or file was deleted → call `deskfree_state` to see current files
+  - File content is malformed (invalid markdown, control characters)
   - Network timeout → retry once, then complete as blocked if persistent
-- **Solution**: Validate markdown content before sending, handle network errors gracefully
+- **Solution**: Validate content before sending, handle network errors gracefully
 
 #### Sub-agent Spawn Failures
 - **Common causes**: Resource limits, configuration errors, invalid task context
@@ -483,44 +602,41 @@ If anything goes wrong mid-task:
 
 ## Common Workflow Patterns
 
-### Pattern 1: Research & Analysis (Sub-agent Recommended)
+### Pattern 1: Research & Analysis with File Output
 
 ```
 Main Session:
-1. deskfree_state()                    → check workspace
+1. deskfree_state()                    → check workspace + files
 2. deskfree_suggest_tasks([{
      title: "Research competitor HumanLayer",
-     instructions: "Analyze their product, pricing, and positioning vs DeskFree"
+     instructions: "Analyze their product, pricing, and positioning vs DeskFree",
+     newFile: { name: "HumanLayer Analysis", description: "Competitor analysis report" }
    }])
 3. [human approves task]
-4. deskfree_start_task(taskId)         → get task context
-4. spawn_subagent(research_prompt)     → background research
+4. deskfree_start_task(taskId)         → get task context + fileContext (empty file pre-created)
+5. spawn_subagent(research_prompt)     → background research
 
 Sub-agent:
-1. deskfree_update_deliverable()       → initial outline
+1. deskfree_update_file(fileId, "# HumanLayer Analysis\n\n## Summary\n...")   → initial outline
 2. [research work...]
-3. deskfree_update_deliverable()       → interim findings  
+3. deskfree_update_file(fileId, "...")  → interim findings
 4. [more research...]
-5. deskfree_update_deliverable()       → final report
-6. deskfree_complete_task(taskId, "done")
+5. deskfree_update_file(fileId, "...")  → final report
+6. deskfree_complete_task(taskId, "done", summary: "Analysis complete — 3 key differentiators identified, full report in file")
 ```
 
-### Pattern 2: Quick Fix (Main Session)
+### Pattern 2: Quick Fix (Main Session, No File)
 
 ```
 1. deskfree_state()                    → check current state
 2. deskfree_suggest_tasks([{
-     title: "Fix broken login endpoint", 
+     title: "Fix broken login endpoint",
      instructions: "Apply hotfix for 500 error in /auth/login"
    }])
 3. [human approves task]
 4. deskfree_start_task(taskId)         → claim the work
-4. deskfree_update_deliverable()       → "Investigating issue..."
 5. [fix the code...]
-6. deskfree_update_deliverable()       → "Applied fix, testing..."
-7. [verify fix...]
-8. deskfree_update_deliverable()       → "Fix verified and deployed"
-9. deskfree_complete_task(taskId, "done")
+6. deskfree_complete_task(taskId, "done", summary: "Fixed null pointer in auth middleware, deployed to staging")
 ```
 
 ### Pattern 3: Blocked Task with Human Input
@@ -529,7 +645,7 @@ Sub-agent:
 1-5. [normal task startup...]
 6. [encounter blocker - need API key]
 7. deskfree_send_message("Need the new Stripe API key to complete this integration. Where can I find it?")
-8. deskfree_update_deliverable()       → save partial progress
+8. deskfree_update_file(fileId, "...")  → save partial progress if task has a file
 9. deskfree_complete_task(taskId, "blocked")  → hand off to human
 ```
 
@@ -538,13 +654,16 @@ Sub-agent:
 ```
 Heartbeat check:
 1. deskfree_state()                    → shows pendingEvaluations: [{taskId: "abc", ...}]
-2. deskfree_claim_evaluation("abc")    → get evaluation context  
-3. [analyze task, messages, current ways of working...]
+2. deskfree_claim_evaluation("abc")    → get evaluation context (task, messages, waysOfWorking, initiative?)
+3. [analyze task summary, messages, current ways of working, initiative if present...]
 4. deskfree_submit_evaluation({
      taskId: "abc",
      reasoning: "Found a new pattern for API error handling...",
-     hasChanges: true,
-     updatedContent: "# Ways of Working\n\n## API Integration\n[new section]..."
+     globalWoW: {
+       hasChanges: true,
+       updatedContent: "# Ways of Working\n\n## API Integration\n[new section]..."
+     },
+     initiative: { hasChanges: false }
    })
 ```
 
@@ -552,7 +671,7 @@ Heartbeat check:
 
 **Good (short, scannable, action-oriented):**
 - "Research competitor HumanLayer"
-- "Deploy staging hotfix"  
+- "Deploy staging hotfix"
 - "Write API docs for /users endpoint"
 - "Debug memory leak in worker process"
 - "Review Q3 performance metrics"
@@ -570,12 +689,13 @@ Heartbeat check:
 
 | Practice | Rationale | Example |
 |---|---|---|
-| **Update deliverable early and often** | Shows progress, survives interruptions | Update outline immediately, add sections as you work |
+| **Update file early and often** | Shows progress, survives interruptions | Update outline immediately, add sections as you work |
 | **Use descriptive commit-style titles** | Easy to scan, actionable | "Fix authentication timeout in Safari" |
 | **Send progress messages for long tasks** | Humans know you're working | "25% complete - analyzed 3 of 12 competitor features" |
 | **Complete blocked tasks with explanation** | Clear handoff to humans | Message: "Need AWS credentials", then complete as blocked |
-| **Start with template deliverables** | Consistent structure, never empty | Use the markdown template every time |
+| **Start with template file structure** | Consistent structure, never empty | Use the markdown template every time |
 | **Handle 404/409 gracefully** | Race conditions are normal | Check state and pick different task, don't retry same task |
+| **Provide meaningful summary on done** | Humans see this first | "Wrote full API docs for /users endpoint — 12 methods documented" |
 
 ### ❌ Don't Do This
 
@@ -584,19 +704,21 @@ Heartbeat check:
 | **Leave tasks in `bot` (is_working=true)** | Blocks the workspace indefinitely | Always complete as `done` or `blocked` |
 | **Retry `deskfree_state` in loops** | Wastes resources, indicates logic error | Call once per decision point |
 | **Start multiple sub-agents per task** | Creates confusion, race conditions | One sub-agent per task maximum |
-| **Update deliverable only at the end** | Progress lost if interrupted | Update incrementally throughout work |
+| **Update file only at the end** | Progress lost if interrupted | Update incrementally throughout work |
 | **Ignore 409 conflicts on task claims** | Causes infinite retry loops | Accept conflict, check state, pick different task |
 | **Create tasks without clear actions** | Unclear what needs doing | Use imperative verbs: "research X", "fix Y", "analyze Z" |
 | **Send messages instead of completing blocked** | Task stays in limbo | Send message explaining blocker, then complete as blocked |
+| **Complete "done" without a summary** | Human can't quickly understand outcome | Always provide a 1-3 sentence summary of what was accomplished |
 
 ### Common Gotchas
 
 - **Auto-threading stops after `deskfree_complete_task`** → Pass explicit `taskId` for post-completion messages
-- **Empty deliverable content is rejected** → Always provide meaningful content, even if just an outline
-- **Sub-agents can't create tasks** → Only orchestrator (main session) can create and claim tasks  
+- **Empty file content is not useful** → Always provide meaningful content, even if just an outline
+- **Sub-agents can't create tasks** → Only orchestrator (main session) can create and claim tasks
 - **Ways of working updates require `hasChanges=true`** → Explicitly set flag when submitting changes
 - **Task titles are visible to humans** → Make them professional and descriptive
 - **Evaluation reasoning is important** → Explain your analysis even if no changes are made
+- **summary is required for outcome "done"** → Plan what you'll write before completing
 
 ## Human Review Outcomes