Octopad

Fetch deeper workspace context mid-session — call after start_session when you need richer data for a specific entity or are switching focus. USE by mode: - "task" → full task data: status, deps, subtasks, linked pages, related knowledge, stream tracker. Call before starting any WORK task. Accepts task_name (fuzzy-matched). Also accepts work_stream_name as an entry point — auto-resolves to the next task in that stream for you. If the resolved task has pending subtasks, auto-drills to the next actionable subtask. Resolution priority: task_name > work_stream_name. - "work_stream" → tracker content, activity log, tasks by status, stream knowledge. USE for stream status checks and project updates. Stream-selection rule, most-specific-first: when the user names 2+ streams, ALWAYS use work_stream_names: ["A","B","C"] (one targeted call). When they name one, use work_stream_name. Only omit BOTH when the user explicitly asks for a workspace-wide view of EVERY active stream — that path returns all streams unfiltered, is the most expensive shape, and should be reserved for genuine "what is everything in flight" questions; do NOT default to it when the user named specific streams. NEVER call this tool in parallel with different work_stream_name values to survey multiple streams. If the user implied resuming or continuing work on a stream, re-call with mode="task" + work_stream_name instead — this mode does not select the next task. - "goal" → goal details, contributing streams, task progress. USE for goal-progress reviews. Accepts goal_name. NOT for: to-do list / priorities → use todo_list(action:"generate"). Knowledge search → use search. Workspace orientation → use start_session. Key params: workspace_id, mode (task|work_stream|goal), task_name (mode=task), work_stream_name / work_stream_names (mode=task or work_stream), goal_name (mode=goal). Requires an active session (call start_session first).

build_context

Manage company goals — the strategic layer above work streams. Goals define "what" and "why"; work streams handle "how". USE to create goals, update status, and link work streams to goals (primary + secondary contribution). link_stream: only time-bound streams can link to goals — ongoing streams must NOT be linked (they represent permanent areas of work, not goal-bound efforts). NOT for goal progress or contributing tasks → build_context(mode: "goal") returns richer data. **Goal closure (status="achieved"):** pick `closure_method`: "draft_page" requires `post_mortem_content` (body-only markdown, ≥200 chars — DO NOT include YAML frontmatter or an H1 title, the server prepends the standardized header) and optional `post_mortem_page_title` (defaults to "<Goal Title> — Post-Mortem"). The post-mortem page lands automatically in the workspace's system Archive folder alongside archived stream trackers — no folder argument is needed or accepted. "skip" requires `skip_post_mortem_rationale` (≥20 chars) — only when the user explicitly accepts no post-mortem artifact. Before drafting, read each linked stream's Rationale, Definition of Success, Scope, Closing Report, and Activity Log via pages; plus completed tasks' completion comments. The tool runs the full close lifecycle atomically: goal flip + post-mortem page + linked-completed-stream cascade (archive + task archive + audit comments). Fails if any time-bound linked stream is still active, if the goal already has a post-mortem page (re-close fence), or on any mid-transaction error (rolls back everything). **Goal reopen (status="active" from achieved):** requires `reopen_rationale` (≥20 chars). Appends a "### Re-opened" section AND a "### Superseded" marker to the existing post-mortem page (fail-closed), then unlinks the page from the goal (sets `page_id` to NULL). Each close cycle files a fresh post-mortem page; prior post-mortems stay on disk as workspace artifacts. Flips status, cascade-unarchives streams that were auto-archived by this goal's closure (via the archived_by_goal_id FK — not text matching). Optional `reopen_streams="all"` flips those streams further from completed back to active. **Org goals (task ⑦):** create with scope="organization" for a company-wide goal shared across the org (org admins only; default "workspace"); share_to_org / unshare_from_org move an existing goal between this workspace and the org in place (org admins only, intra-org); parent_goal ladders a goal under a parent (optional, same-org guarded — clear with an empty string on update). Closing/reopening an ORG goal works like a workspace goal but is org-admin-gated: the post-mortem is filed as an org-scoped page (no folder) and closure blocks on, then cascade-archives, the org goal's contributing streams across ALL workspaces in the org (reopen un-cascades them). Key params: action (list|get|create|update|delete|restore|link_stream|unlink_stream|share_to_org|unshare_from_org), goal_id, title, scope, parent_goal, closure_method + post_mortem_content/skip_post_mortem_rationale (achieved), reopen_rationale + reopen_streams (reopen), work_stream_id + primary_goal_id + secondary_goal_ids (link_stream). Requires an active session.

goals

Individual task operations — get, create, update, delete, restore, list. USE create to start work, update for status changes, list to browse the backlog. USE get for full details of a single task (description, dependencies, subtasks, linked files/pages); for surrounding context — comments, related knowledge, activity — use build_context(mode: "task"). The action param also covers approval-gated completions and dependency edges. NOT for batch creation (→ batch_tasks), bulk field overrides across many tasks (→ bulk_tasks), standalone comments (→ task_comments), or work prioritization / daily to-do lists (→ todo_list). NOT for personal reminders, calendar alerts, or shopping/grocery lists — out of scope for Octopad. Requires an active session.

tasks

Your personal daily to-do list — the rolling, per-user queue of what YOU are working on today or this week (items due this week or sooner). USE when the user asks about their list or today's priorities with NO named entity (e.g. "what should I work on", "show my to-do list", "reorder my list"). If the user names a task, stream, or goal — or says resume/continue/pick up X — use build_context instead. Actions (see the action param for behavior): next, get, generate, add, reorder, remove, defer. NOT for multi-week or multi-phase planning → use the task tree (tasks + task_dependencies), never this tool. NOT for task status updates → tasks. NOT for stream health → build_context(mode: "work_stream"). NOT for personal reminders, calendar alerts, or shopping/grocery lists — out of scope for Octopad. Requires an active session.

todo_list

Cross-type retrieval — find anything in the workspace by meaning or exact phrase. Combines keyword (ILIKE), semantic (embedding), and section (page-heading) search into one relevance-ranked result set. USE to discover information without knowing which content type holds it, or for broad questions ("what do we know about X?"). Narrow with methods[] (keyword/semantic/sections) and types[] (decision, key_fact, question, risk, page, file, task, chunk, task_comment, section) — see those params, including the section/sections coupling. NOT for creating or editing content (→ knowledge, pages, files) or loading structured entity context (→ build_context). For 2+ independent queries, use batch_search (parallel). Archived tasks/comments are excluded unless include_archived:true. Requires an active session.

search

Multi-query parallel search — run 2–10 independent searches in one call. USE when you need to check multiple topics before acting: refreshing a page across domains, verifying decisions before a plan, finding pages to link to a new task. Pass an array of query objects, each with `query` (required), optional `label`, `types`, and `methods`. Returns results grouped by query label. By default archived tasks/comments are excluded — pass include_archived:true to include them. NOT for single lookups (→ `search`). Requires an active session.

batch_search

Create multiple tasks in one call with optional parent-child wiring via parent_ref "@N". USE when a planning session produces 3+ related tasks — avoids round-trips and preserves hierarchy in one atomic operation. NOT for single task creation (use tasks), bulk field overrides (use bulk_tasks), or commenting (use task_comments). NOT for personal reminders, calendar alerts, or shopping/grocery lists — those are out of scope for Octopad. Key params: tasks[] array — each item supports title, description, work_stream_id, priority, parent_ref or parent_task_id. LIMITS: max 20 tasks per call, max 30,000 chars total across all titles + descriptions. If the payload is too large, split into smaller batches — do not shorten descriptions. If a batch times out, DO NOT retry blindly — check if tasks were created first, as the server may have processed the request despite the timeout. DEPENDENCIES: When creating 2+ tasks, every task MUST include depends_on_refs — use [] for independent tasks, ["@N"] for a dependency on task at index N in this batch, or the name or UUID of an existing task to depend on it. This wires task_dependencies rows automatically. Requires an active session.

Apply the same field override to multiple tasks at once — status, assignee, work stream, priority, or archive flag. USE when closing a sprint, reassigning a block of work, or archiving completed tasks in bulk. NOT for creating tasks (use batch_tasks), per-task changes (use tasks), or comments (use task_comments). Key params: action (update/archive, default: update), task_ids (array of titles or UUIDs), then any shared field — status, assigned_to, work_stream_id, is_archived + archive_rationale. For archive: archive_rationale is required. MOVING A SUBTREE TO ANOTHER WORK STREAM: a subtask always lives in its parent's work stream, so move the PARENT task(s) and the subtasks follow automatically — do NOT list subtasks to move them. A subtask whose parent is not in the move is left where it is and reported back (it is not counted as moved). Requires an active session.

End the current session and persist a summary for future context — auto-generates from activity log if none provided, but an explicit summary is richer. USE: at the end of every session. Pass a brief plain-text recap of what was accomplished so future sessions can pick up without losing context. NOT required to keep the session alive — sessions auto-expire — but calling explicitly stores a better summary and triggers the session scribe. Key params: workspace_id (omit to auto-close the most recent active session), summary (plain-text recap of session work), session_id (omit to auto-close the most recent active session).

Capture user sentiment about the product — complaints and praise logged against the workspace. USE immediately when the user expresses positive or negative sentiment mid-session. NOT for task blockers or session notes → use task_comments instead. ⚠️ PRIVACY RULE (hard stop): content must describe Octopad UX/behavior only. NEVER include the user's name, task titles, project names, session data, UUIDs, email addresses, or anything that belongs to the user. Describe the product behavior, not the specific user instance. Server-side validation will reject UUIDs and email patterns. ✅ DO: "Task save action sometimes fails silently — user noticed after submit" ❌ DON'T: "David complained that his task 'Fix login flow' won't save" (leaks name + task title) Redact action: call ONLY when the user explicitly asks to redact a specific feedback entry — never on your own initiative. Key params: action (create|list|redact), sentiment (complaint|praise, required for create), content (create: max 500 chars), category (free-text tag e.g. "ux", "onboarding"), feedback_id (redact: UUID of the entry to mask). Requires an active session.