docs/capabilities.md

# Headless capability matrix

Quick reference for what Headless inspects, what Cobuild builds, and what can be
re-run. For the operating workflow, start with
[`skills/dataiku-headless/SKILL.md`](../skills/dataiku-headless/SKILL.md) and load
its object-specific references as directed.

## The rule

**Flow and analytic logic is always built by Cobuild.** Headless has no tool to create
or change recipe logic, code, inputs, or outputs, or to create or modify the definition
of an ML analysis, dashboard, insight, agent, agent tool, scenario, webapp, wiki article,
data quality rule, knowledge bank, semantic model, or evaluation store. The container
execution override below changes only which container an existing object runs in.

Headless writes Dataiku objects directly in four cases: **bootstrap** (get a project
or local content onto the instance so Cobuild has something to work with), **project
configuration**, **cross-project**, and **instance-level administration**. It also
re-runs assets that already exist. Some bootstrap writes do land inside a project —
see the table below.
Local profile actions are listed separately because they only change which Dataiku
instance the local client targets.


## Surface

**129 tools** · 93 read · 22 direct Dataiku write · 6 Cobuild · 4 execute · 3 local
profile · 1 connection test

| Bucket | # | Scope |
|---|---|---|
| Read / inspect | 93 | Never mutates |
| Direct Dataiku write | 22 | Bootstrap, project configuration, cross-project, admin |
| Cobuild conversation | 6 | All flow and analytic building |
| Execute | 4 | `build_datasets`, `run_recipe`, `run_scenario`, `abort_job` |
| Local profile action | 3 | `configure_instance`, `switch_instance`, `delete_instance` |
| Connection test | 1 | `test_connection` |

Buckets count each tool once by what it does. The tables below group by area instead, so a
tool can appear in the **Local instance targeting** section while counting in a different
bucket here.

## Built by Cobuild — limited direct exceptions

Three partial exceptions: Headless can create a dataset from a local file, create an
empty managed folder, and select container execution for an existing object (see
*Handled directly by Headless*). It cannot build or change analytic logic here.

| Area | Inspect | Direct action |
|---|---|---|
| Datasets | `list_datasets`, `get_dataset_info`, `get_dataset_sample`, `get_dataset_profile`, `get_dataset_metrics`, `get_dataset_column_descriptions`, `export_dataset` | `build_datasets` |
| Recipes | `list_recipes`, `get_recipe_settings` | `set_container_exec_config`, `run_recipe` |
| Flow & zones | `get_flow_graph`, `list_flow_zones`, `get_flow_object_metadata` | — |
| ML analyses | `list_ml_analyses`, `get_ml_analysis_summary`, `get_ml_analysis_settings`, `list_ml_analysis_models`, `get_ml_model_details` | `set_container_exec_config` (single-ML-task analyses) |
| Saved models | `list_saved_models`, `list_saved_model_versions`, `get_saved_model_version_details` | — |
| Agents | `list_agents`, `get_agent_settings`, `list_agent_versions`, `list_agent_tools`, `get_agent_tool_settings` | `set_container_exec_config` (agent tools) |
| Agent reviews | `list_agent_reviews`, `get_agent_review`, `list_agent_review_tests`, `list_agent_review_runs`, `get_agent_review_run_results` | — |
| Scenarios | `list_scenarios`, `get_scenario_settings`, `get_scenario_run_history`, `list_messaging_channels` | `run_scenario` |
| Dashboards & insights | `list_dashboards`, `get_dashboard_settings`, `list_insights`, `get_insight_settings` | — |
| Webapps | `list_webapps`, `get_webapp_settings`, `get_webapp_state` | `set_container_exec_config` |
| Wikis | `list_wiki_articles`, `get_wiki_article` | — |
| Data quality | `list_data_quality_rules`, `get_data_quality_status`, `get_data_quality_rule`, `get_data_quality_rule_results`, `get_data_quality_rule_history` | — |
| LLMs & knowledge banks | `list_llms`, `get_llm_info`, `list_knowledge_banks`, `get_knowledge_bank_settings`, `search_knowledge_bank`, `list_retrieval_augmented_llms`, `get_retrieval_augmented_llm_settings` | `set_container_exec_config` (knowledge banks) |
| Semantic models | `list_semantic_models`, `get_semantic_model_version_settings` | — |
| Evaluation stores | `list_evaluation_stores`, `get_evaluation_store_details` | — |

## Driving Cobuild

| Tool | Use |
|---|---|
| `start_cobuild_conversation` | Open a retained conversation on a project |
| `send_cobuild_message` | Ask Cobuild to inspect a project, or to build or change something — edits are opt-in via allow_edit_project |
| `answer_cobuild_question` | Answer a question Cobuild asked, resuming its pending work |
| `answer_cobuild_confirmation` | Approve or cancel a deletion Cobuild proposed; `APPROVE` deletes the listed objects |
| `get_cobuild_turn_status` | Poll a turn; recovers after a timeout or cancellation |
| `list_cobuild_conversations` | Find existing conversations for this instance and project |

## Handled directly by Headless

No Cobuild involved. Scope says what kind of access, and where a write lands.

| Area | Inspect | Act | Scope |
|---|---|---|---|
| Projects | `count_projects`, `list_projects`, `get_project_metadata`, `get_project_variables`, `get_project_settings` | `create_project`, `set_project_variables`, `update_project_settings` | Bootstrap and project configuration — direct writes are **in-project** |
| Container execution placement | `get_recipe_settings`, `get_ml_analysis_settings`, `get_webapp_settings`, `get_knowledge_bank_settings`, `get_agent_tool_settings`, `list_container_exec_configs` | `set_container_exec_config` | Project configuration, **in-project** — sets which container a recipe, ML task, WebApp backend, Knowledge Bank, or agent tool runs in. Saved-model retrains use their training recipe's `params.containerSelection`. |
| Uploaded Files datasets | — | `create_upload_dataset` | Bootstrap, **in-project** — supplied rows in HTTP; local files in stdio only |
| Managed folders | `list_managed_folders`, `get_managed_folder_info`, `get_managed_folder_contents` | `create_managed_folder`, `upload_file_to_managed_folder` | Bootstrap, **in-project** — local-file upload is stdio only |
| Project libraries | `list_project_library`, `read_project_library_file`, `search_project_library`, `validate_project_library_file` | `write_project_library_file` | Bootstrap, **in-project** — local-file write is stdio only |
| Project folders | `list_project_folders`, `get_project_folder` | `create_project_folder`, `move_project_to_folder`, `delete_project_folder` | Cross-project |
| Code environments | `list_code_envs` | `create_code_env`, `update_code_env`, `delete_code_env` | Instance-level |
| Plugins | `list_plugins`, `list_plugin_usages` | `update_plugin`, `delete_plugin` | Instance-level — `update_plugin` is stdio only |
| Users | `list_users` | `create_user`, `update_user`, `delete_user` | Instance-level |
| Groups | `list_groups` | `create_group`, `update_group`, `delete_group` | Instance-level |
| Jobs | `list_jobs`, `get_job_status`, `get_job_log`, `get_future_status`, `wait_for_job` | `build_datasets`, `run_recipe`, `run_scenario`, `abort_job` | Execution — re-runs or stops assets that already exist |
| Connections | `list_connections`, `get_connection_info`, `test_connection` | — | Read-only |
| Instance settings | `list_container_exec_configs`, `list_spark_configs`, `get_licensing_status` | — | Read-only |
| Data collections & sharing | `list_data_collections`, `list_data_collection_objects`, `list_shared_objects` | — | Read-only |

The **in-project** writes above configure or supply a project; they do not build its
analytic logic. None of them build recipe logic, a model, or an agent.

## Local instance targeting

Local client configuration, not Dataiku objects.

| Tool | Effect |
|---|---|
| `configure_instance` | Connect a local stdio instance; opens a local page for URL, instance type, and API key (disabled in HTTP mode) |
| `switch_instance` | Change the active instance; in HTTP mode saves only the authenticated user’s selected catalog instance |
| `list_instances`, `get_current_instance` | Show configured instances, their declared types, and the active one; `get_current_instance` includes the Dataiku version when available |
| `delete_instance` | Removes a **saved connection profile from the local config file**. Does not touch the Dataiku instance. |