com.killbottleneck/killbottleneck

Add a subtree of nodes to an existing map under parent_id (or under the apex when parent_id is omitted). A node is a goal; a node with an assignee (owner) OR a deadline IS a task — that is the only kind of task in killBottleneck (there is no separate task record; new work = new node). NOTE: this re-computes the layout of the whole map. Max 200 nodes per call. Returns the updated tree.

Create a personal calendar EVENT with a time (meeting, call, dentist…) — NOT a task and not part of any map. Optional participants (e-mails of instance members from list_people; each sees the event in their calendar) and a reminder N minutes before (in-app + e-mail). Times are the instance's local time.

Create a new goal map from an outline. The map gets an apex (root goal) from `title`/`apex_text`; `outline` items become nested nodes. Layout is computed automatically. Max 200 nodes per call. Returns the created tree with node ids.

Set a timed REMINDER for a map node relative to its deadline: offset_days before the deadline (0 = on the deadline day, 1 = the day before) at time HH:MM, instance local time. One reminder per person and node (calling again replaces it). Does NOT change the deadline; the node must already have one (set it with update_node first). Private to the key owner.

Create an automation rule on a map: WHEN trigger fires (and optional AND conditions match) DO the actions in order. Rules run for changes made in the UI, via API and by agents alike. Structural limits: 50 rules per map, 10 actions, 20 conditions — there is NO monthly run quota. A rule applies only to future events, never retroactively. node_id scopes the rule to one node (required for schedule rules whose actions target a node).

Delete a node INCLUDING its whole subtree. The apex (root) cannot be deleted and whole maps cannot be deleted via the API. Irreversible — read the map first and double-check the node id.

Delete an automation rule. Its run log stays (with the rule name snapshot). Irreversible.

Delete a rule template from the library (author or admin only). Rules already created from it are independent copies and stay untouched.

Read one map as an indented tree with node ids, statuses ([✓] done, [~] in progress, [ ] todo), deadlines and owners. The header shows the key's access level (owner/edit = full write; work and read = only the status of the key owner's own nodes, like ticking off in the app). Always call this before modifying a map you have not read yet.

Read the organization structure (the org map): positions and functions with node ids, holders and deputies. Use the node ids as dynamic rule targets "position:<nodeId>" / "deputy_of_position:<nodeId>". Read-only — holders and deputies are appointed by an admin in the app.

Read the portfolio overview across all team and shared maps the key owner can read (private maps are excluded, exactly like the Organization page): per-project completion, overdue and stuck items, people with overdue work and a 7-day change summary. Optional today=YYYY-MM-DD. Read-only.

List the key owner's calendar events (own and invited) in a day range; default today−365 … +730. Read-only.

List goal maps the key owner can see — own, team and shared maps (id, title, node count, last update, access: owner/edit/work/read). Use archived=true to list archived maps instead.

List the people work can be assigned to: instance members (e-mail, display name, role) and external contacts visible to the key owner (their owner_email is a pseudo e-mail usable as owner). Use these e-mails as `owner` in create_map/add_nodes/update_node and in set_owner rules — an unknown e-mail is rejected. Read-only.

Read the run log of a map's automation rules (newest first, max 100): what fired, on which node, ok/failed/skipped and what the actions did. skipped = a safety stop (rule chain depth or per-save cap), detail says which.

List the instance-wide library of rule templates (shape of a rule without a map or node scope). To use one, read it and call create_rule on the target map with its trigger/conditions/actions — the created rule is an independent copy.

List automation rules of a map: id, name, enabled, scope node, trigger, conditions, actions, last_fired and last_error (a non-empty last_error means the rule is misconfigured and its owner was notified).

Save a rule shape into the instance-wide template library (create, or update with template_id — only the author or an admin may update). Templates carry no map and no node scope; create_subnodes may only use parent=trigger_node. Template names are unique.

Update fields of one node: title, status (todo/in_progress/done), description, deadline (YYYY-MM-DD, empty string clears), planned_on (YYYY-MM-DD, today to +7 days, empty string clears — WHEN the key owner plans to work on it; this is how killBottleneck expresses priority, never by moving the deadline), owner (e-mail, empty string clears), wait_for_children, colour, who performs it (executor_kind / executor_name) and the automation wish (automation_wanted / automation_note). Unknown fields are rejected with the list of allowed ones. Marking status done may unblock waiting nodes, notify their owners and trigger automations on them.

Update an automation rule. Pass only `enabled` to toggle it on/off; otherwise pass the FULL new shape (name, trigger, actions, optional conditions/node_id) — partial field edits are not merged. Edits apply to future events only and clear the rule's error state.