@hybridaione/hybridclaw 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -2,43 +2,89 @@
 
 ## [Unreleased]
 
+## [0.9.2](https://github.com/HybridAIOne/hybridclaw/tree/v0.9.2)
+
+### Added
+
+- **Skill sync and packaged Datalion workflow**: Added `skill sync`, updated
+  TUI help/commands, shared import-argument parsing, and the repo-shipped
+  Datalion community skill with bundled setup/capabilities docs.
+- **Meme generation community skill**: Added a packaged meme-generation skill
+  with reusable scripts, template data, and cached output reuse for community
+  image workflows.
+- **Workspace search hardening**: Added stricter workspace `glob` and `grep`
+  handling in the container runtime for safer repository searches.
+
+### Changed
+
+- **Web chat branching and history flow**: Improved web chat controls,
+  branch-aware history routing, paging persistence, and related stdin/history
+  handling so browser sessions behave more predictably.
+- **Shared type and search-tool internals**: Split the old shared type barrel
+  into focused modules and moved container search logic into a dedicated
+  `search-tools` module.
+- **Skill import UX cleanup**: Centralized import warning text, shared the
+  skill-import argument parser, removed sync/skip-scan quick entries from
+  menus, and simplified optional import-result guard fields.
+
+### Fixed
+
+- **WhatsApp restart and ack recovery**: Reduced restart replay failures,
+  captured and cleared ack reactions more reliably, dropped timestampless
+  append-history writes, and hardened reconnect handling.
+- **TUI history-arrow behavior**: Restored arrow-key prompt history when the
+  slash menu has no matches while keeping those keys reserved for history
+  navigation.
+- **Agent skill overwrite protection**: `agent install` now requires
+  `--force` before overwriting imported skills instead of silently replacing
+  existing content.
+- **Static docs publishing and QMD paging stability**: Synced the static docs
+  shell with the gateway renderer, added `.nojekyll` for GitHub Pages, and
+  persisted branch paging state while quieting QMD timeout noise.
+- **Meme skill runtime hardening**: Tightened meme fetch error handling,
+  file-path validation, and cache reuse so the packaged skill is safer and
+  cheaper to run repeatedly.
+
 ## [0.9.1](https://github.com/HybridAIOne/hybridclaw/tree/v0.9.1)
 
 ### Added
 
-- **Prompt-side context references and current-turn uploads**: Added inline
-  `@file:`, `@folder:`, `@diff`, `@staged`, `@git:<count>`, and `@url:`
-  context references so prompts can pull workspace or web context directly,
-  plus web chat and TUI uploads/paste support for current-turn files.
-- **Community skill imports and package-declared skill imports**: Added
-  `hybridclaw skill import [--force] <source>` and `/skill import` for
-  packaged `official/<skill>` sources plus `skills-sh`, `clawhub`, `lobehub`,
-  `claude-marketplace`, `well-known`, and GitHub repo/path refs. `.claw`
-  agent installs can now resolve manifest-declared skill imports into the
-  agent workspace.
-- **Browsable development docs shell**: Added the built-in `/development` docs
-  browser with raw-markdown and copy-as-markdown actions for repo-shipped
-  docs.
+- **Inline prompt context references**: Added `@file:`, `@folder:`, `@diff`,
+  `@staged`, `@git:<count>`, and `@url:` so prompts can pull repository or web
+  context directly.
+- **Current-turn web chat and TUI attachments**: Added upload/paste support
+  for files and clipboard media in the built-in chat UI and TUI, including
+  uploaded-media summaries for supported content.
+- **Community skill imports and docs browser**: Added `hybridclaw skill import`
+  and `skill learn`, packaged and hub-backed skill sources, manifest-declared
+  skill imports during `.claw` install, and the built-in `/development` docs
+  browser with raw-markdown views.
 
 ### Changed
 
-- **Adaptive skill and agent archive command naming**: Standardized the
-  adaptive-skill workflow on `skill learn` (`--apply`, `--reject`,
-  `--rollback`) and promoted `agent export` / `agent install` as the primary
-  `.claw` archive verbs while keeping `pack` / `unpack` aliases.
-- **On-demand gateway/provider health probing**: Gateway status and
-  `/api/status` now use TTL-cached on-demand probes for HybridAI and local
-  backends instead of background polling loops.
+- **Gateway/provider health probing**: Status endpoints now use TTL-cached
+  on-demand probes for HybridAI and local backends instead of background
+  polling loops, with async status flow and better probe-site error handling.
+- **CLI command structure**: Split the large CLI handlers into focused command
+  modules with shared lazy-loader and flag-parsing helpers.
+- **Skill import source coverage**: Community imports expanded from packaged
+  sources into hub-backed and GitHub-backed skill sources, with web docs
+  navigation updated to expose the new workflows.
 
 ### Fixed
 
-- **HybridAI base-url reachability reporting**: HybridAI reachability checks,
-  `/api/status`, and operator hints now honor `HYBRIDAI_BASE_URL`
-  consistently, including preview or local deployments.
-- **Uploaded media and context-reference hardening**: Tightened uploaded-media
-  cache validation, MIME filtering, per-auth upload quotas, symlink escape
-  blocking, URL redirect blocking, and bounded remote fetches for attached
-  prompt context.
+- **HybridAI base-url reachability reporting**: `/api/status` and operator
+  hints now honor `HYBRIDAI_BASE_URL` consistently and probe actual backend
+  reachability instead of assuming credentials imply connectivity.
+- **Uploaded media hardening**: Tightened cache-dir resolution, path
+  validation, MIME filtering, per-auth upload quotas, and filename handling
+  for web chat and TUI attachments.
+- **Context-reference safety and command preservation**: Blocked symlink
+  escapes, URL redirects, and unbounded URL fetches for attached prompt
+  context while preserving skill invocations with injected context.
+- **CLI install output for imported skills**: `agent install` now tolerates
+  missing imported skills in the CLI summary instead of failing the output
+  path.
 
 ## [0.9.0](https://github.com/HybridAIOne/hybridclaw/tree/v0.9.0)
 

package/community-skills/datalion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: datalion
-description: Use this skill when the user wants DataLion workflows such as creating a project, uploading CSV data, reading chart tables, or coordinating report, dashboard, and export work through a configured datalion MCP server and related API or UI paths.
+description: Use this skill when the user wants DataLion workflows such as listing, reading, creating, or editing projects, inspecting data sources, importing Excel or CSV data, working with reports and report tabs and codebooks, reading chart tables, or coordinating dashboard and export work through a configured datalion MCP server and related API or UI paths.
 user-invocable: true
 metadata:
   hybridclaw:
@@ -17,8 +17,11 @@ metadata:
 
 # DataLion
 
-Use this skill for DataLion project, data-import, chart-table, report,
-dashboard, and export workflows.
+Use this skill for DataLion project, project-settings, data-import, codebook,
+chart-table, report, report-tab, dashboard, and export workflows.
+
+In DataLion, "tab" and "dashboard" are used interchangeably for the report
+subpages managed under a report.
 
 ## Default Strategy
 
@@ -34,12 +37,17 @@ dashboard, and export workflows.
 ## Setup
 
 - Run HybridClaw in host sandbox mode for this local Node-based MCP server.
+- Install the bridge dependencies before first use:
+  `npm --prefix <path-to-your-datalion-repo>/mcp install`
 - Keep `DATALION_API_TOKEN` inside MCP server config `env`, never in tracked
   files or chat.
 - Use the MCP server name `datalion` so tools appear as `datalion__...`.
+- For `hybridclaw gateway mcp add ...`, pass the JSON config as one quoted
+  shell argument. In `zsh`, unquoted `{...}` and `[...]` will be expanded
+  before HybridClaw sees them.
 - See
   [references/setup-and-capabilities.md](references/setup-and-capabilities.md)
-  for a ready-to-paste `/mcp add` example, dependency note, and ability
+  for ready-to-paste CLI and TUI examples, dependency notes, and ability
   requirements.
 
 ## Working Rules
@@ -47,19 +55,47 @@ dashboard, and export workflows.
 - Always state whether you are using MCP, REST API, or browser/UI automation.
 - Resolve the exact project, report, dashboard, export, or chart before
   mutating anything.
-- The current bridge directly supports only project creation, data upload, and
-  chart-table reads.
+- The current bridge directly supports project listing, project reads, project
+  creation, project settings updates, data source listing, CSV upload, full
+  Excel/CSV import, report list/create and tab CRUD, chart-table reads, and
+  codebook list, download, generation, deletion, and upload.
+- The bridge also exposes 4 browser URL helpers for project/report/dashboard
+  opening and widget insertion.
+- The current bridge tool surface has 22 tools total: 18 backend MCP actions
+  and 4 browser URL helpers.
+- Prefer `datalion__list_projects` and `datalion__read_project` before writes
+  when the exact target project is not already pinned down.
 - Treat `datalion__upload_data` as a data-import tool, not a generic
   project-update tool.
-- Prefer CSV uploads for MCP. If the source is XLSX/XLS, convert it to CSV
-  first unless the bridge has been updated to accept binary-safe file content.
+- Treat `datalion__edit_project` as a `defsettings` merge tool. It updates only
+  the keys you pass and keeps the existing settings for all other keys.
+- Use `datalion__list_data_sources` to inspect what is already loaded into a
+  project before uploading or troubleshooting data.
+- Prefer `datalion__import_excel_data` when the source is an `.xlsx` workbook or
+  when you want Datalion's full import pipeline, including optional codebook
+  generation during import.
+- Use `datalion__list_codebook` when the user needs a question-level inventory;
+  use `datalion__download_codebook` for the tree structure.
+- For workbook imports, prefer an absolute `localPath` so the bridge can read
+  the file directly.
 - For uploads, confirm filename, header and delimiter assumptions, data source
   name if relevant, and whether existing rows should be truncated.
+- For `import_excel_data`, confirm `projectId`, file path or base64 file
+  content, filename if you are not using `localPath`, whether you want the
+  default main data source (`useDefaultDataSource=true`) or a named data
+  source, and whether `replaceData`, `runCalculations`, `convertComma`,
+  `skipLines`, `comment`, and `createCodebook` should be enabled.
+- For project settings edits, confirm the target `projectId` and the exact
+  `defsettings` keys and values before calling.
 - For chart-table reads, confirm `projectId`, `chartId`, and any filter string
   before calling.
-- For report, dashboard, and export tasks without direct MCP coverage, inspect
-  the local Datalion repo and its OpenAPI or route definitions before choosing a
-  fallback path.
+- For codebook uploads, confirm `projectId`, CSV filename, import mode, and
+  whether any explicit column mapping is needed. The current backend expects
+  `columnMapping` as an array aligned to the CSV header order.
+- For reports, prefer direct MCP coverage first.
+- For dashboard and export tasks without direct MCP coverage, inspect the local
+  Datalion repo and its OpenAPI or route definitions before choosing a fallback
+  path.
 - Keep tokens, auth headers, and exported files out of logs unless the user
   explicitly asks for them.
 
@@ -67,33 +103,123 @@ dashboard, and export workflows.
 
 The current `datalion` bridge exposes these direct tools:
 
+- `datalion__list_projects`
+- `datalion__read_project`
 - `datalion__create_project`
+- `datalion__edit_project`
+- `datalion__list_data_sources`
 - `datalion__upload_data`
+- `datalion__import_excel_data`
+- `datalion__list_reports`
+- `datalion__create_report`
+- `datalion__create_report_tab`
+- `datalion__edit_report_tab`
+- `datalion__delete_report_tab`
+- `datalion__open_project_browser`
+- `datalion__open_report_browser`
+- `datalion__open_dashboard_browser`
+- `datalion__open_add_widget_browser`
 - `datalion__get_chart_table`
+- `datalion__list_codebook`
+- `datalion__download_codebook`
+- `datalion__generate_codebook`
+- `datalion__delete_codebook`
+- `datalion__upload_codebook`
 
 That means:
 
+- project discovery and project detail reads are supported directly
 - project creation is supported directly
+- project settings updates through `defsettings` merges are supported directly
+- project data sources can be listed directly
 - CSV-style data import into an existing project is supported directly
+- workbook and full-pipeline Excel/CSV import are supported directly
+- the full-pipeline import path uses DataLion's datasource service rather than
+  the raw CSV upload path, so it handles type detection, replace/append mode,
+  optional codebook generation, and optional calculations
+- report listing and report creation are supported directly
 - chart tables can be read directly
-- report editing, dashboard editing, and export generation require fallback API
-  or UI paths until the bridge grows more tools
+- codebooks can be listed, downloaded, generated, deleted, and uploaded
+  directly
+- report editing beyond report-tab CRUD, dashboard editing, and export
+  generation require fallback API or UI paths until the bridge grows more tools
 
 ## Common Workflows
 
+For explicit TUI testing, prefer `/skill datalion ...`.
+
+- `/skill datalion create a project named "MCP Smoke Test"`
+- plain natural-language prompts that mention DataLion also work
+- `/datalion ...` may still be routed as a normal message, but it is not a
+  built-in slash-menu command, so do not use slash-menu visibility as the test
+  for whether the skill is installed
+
 ### Create a Project
 
-1. Confirm the project name and any optional metadata.
+1. Confirm the project name and any optional `identcode` or `defsettings`.
 2. Call `datalion__create_project`.
 3. Return the new project ID and recommend the next step, usually data import
    or report/dashboard setup.
 
+### Create a Report
+
+1. Confirm the project ID and report name.
+2. Call `datalion__create_report`.
+3. Note that the report is seeded with a first tab and return both the report
+   ID and first tab ID.
+
+### Manage Report Tabs
+
+1. Call `datalion__create_report_tab` to add a tab to an existing report.
+2. Call `datalion__edit_report_tab` to rename or update a tab.
+3. Call `datalion__delete_report_tab` to remove a tab after confirming the
+   report and tab IDs.
+4. Keep `projectId` aligned with the report or tab/dashboard you are mutating.
+
+### Open In Browser
+
+1. Use `datalion__open_project_browser` for the project screen.
+2. Use `datalion__open_report_browser` for the report editor or a specific
+   report tab/dashboard.
+3. Use `datalion__open_dashboard_browser` for a specific tab/dashboard view.
+4. Use `datalion__open_add_widget_browser` to get the modal URL used to add a
+   question/widget to a tab/dashboard. The actual insertion still happens in
+   the browser UI after the modal is opened.
+
+### Find or Read a Project
+
+1. Call `datalion__list_projects` when the user gives a fuzzy project name or
+   identcode.
+2. Call `datalion__read_project` once you know the `projectId`.
+3. Use the returned `defsettings`, `categoriesCount`, and `dataSourcesCount` to
+   guide the next step.
+
+### Edit Project Settings
+
+1. Confirm `projectId` and the exact `defsettings` keys to merge.
+2. Call `datalion__edit_project`.
+3. Return the updated keys and note that untouched settings stay as they were.
+
 ### Upload Data
 
 1. Confirm the target project ID.
-2. Prefer CSV text input for the current bridge.
-3. Call `datalion__upload_data`.
-4. Return the job ID and the import assumptions you used.
+2. Call `datalion__list_data_sources` first if you need to inspect existing
+   data sources.
+3. Prefer CSV text input for the current bridge.
+4. Call `datalion__upload_data`.
+5. Return the job ID and the import assumptions you used.
+
+### Import Excel or CSV via Datalion Pipeline
+
+1. Confirm `projectId` and the source file path or file content.
+2. Prefer `localPath` for `.xlsx` imports when the file exists on disk.
+3. Use `useDefaultDataSource=true` when you want the workbook imported into
+   the main project data table and codebook generation to read from that same
+   table. Otherwise confirm `dataSourceName`.
+4. Confirm whether `createCodebook` should run during import.
+5. Call `datalion__import_excel_data`.
+6. Return the data source name, imported row count, and whether codebook
+   generation was requested.
 
 ### Read a Chart Table
 
@@ -101,7 +227,28 @@ That means:
 2. Call `datalion__get_chart_table`.
 3. Summarize the result and surface obvious caveats.
 
-### Reports, Dashboards, and Exports
+### Codebook Workflows
+
+1. For question-level inspection, call `datalion__list_codebook`.
+2. For tree-structured inspection, call `datalion__download_codebook`.
+3. For regenerate-from-data workflows, call `datalion__generate_codebook`.
+4. For destructive cleanup, call `datalion__delete_codebook` and confirm
+   whether `includeTextboxes` should be `true`.
+5. For CSV import, call `datalion__upload_codebook` with the filename, file
+   content, import mode, and any index-based `columnMapping` array that should
+   align with the CSV header order.
+
+### Reports
+
+1. Call `datalion__list_reports` to inspect existing reports for a project.
+2. Call `datalion__create_report` to create a new report once the target
+   project and report name are confirmed. The new report is seeded with a
+   first tab and the response includes both IDs.
+3. Use the report-tab tools for tab-level create/edit/delete work.
+4. Treat report edits beyond tab CRUD as fallback work until direct MCP
+   coverage exists.
+
+### Dashboards and Exports
 
 1. Check current `datalion__*` tool coverage first.
 2. If no direct tool exists, inspect `openapi.yaml`, `routes/dashboard.php`, and

package/community-skills/datalion/references/setup-and-capabilities.md

@@ -9,41 +9,231 @@ hybridclaw gateway start --foreground --sandbox=host
 hybridclaw tui
 ```
 
-Add the MCP server from the TUI:
+Add the MCP server from the CLI with the JSON quoted as a single shell
+argument:
+
+```bash
+hybridclaw gateway mcp add datalion '{"transport":"stdio","command":"node","args":["/Users/bkoehler/src/datalion/mcp/mcp-bridge.js"],"env":{"DATALION_API_URL":"https://datalion.test/api/v1/mcp","DATALION_API_TOKEN":"replace-me","DATALION_IGNORE_SSL":"true"},"enabled":true}'
+```
+
+In `zsh`, do not leave the JSON unquoted or the shell will try to expand
+`{...}` and `[...]` before `hybridclaw gateway` receives the config.
+
+Add the same MCP server from the TUI with:
 
 ```text
-/mcp add datalion {"transport":"stdio","command":"node","args":["/absolute/path/to/datalion/mcp/mcp-bridge.js"],"env":{"DATALION_API_URL":"https://datalion.test/api/v1/mcp","DATALION_API_TOKEN":"replace-me","DATALION_IGNORE_SSL":"true"},"enabled":true}
+/mcp add datalion {"transport":"stdio","command":"node","args":["/Users/bkoehler/src/datalion/mcp/mcp-bridge.js"],"env":{"DATALION_API_URL":"https://datalion.test/api/v1/mcp","DATALION_API_TOKEN":"replace-me","DATALION_IGNORE_SSL":"true"},"enabled":true}
 ```
 
-Replace `/absolute/path/to/datalion` with the real checkout path. Do not use
-`~` inside `args`; MCP stdio commands do not run through a shell, so tilde
-expansion is not guaranteed.
+Replace `replace-me` with a real token.
+
+Do not use `~` inside `args`; MCP stdio commands do not run through a shell, so
+tilde expansion will not happen. Use an absolute path like
+`/Users/bkoehler/src/datalion/mcp/mcp-bridge.js`.
 
-If the bridge dependencies are missing:
+Install the bridge dependencies before first use:
 
 ```bash
-npm --prefix /absolute/path/to/datalion/mcp install
+npm --prefix /Users/bkoehler/src/datalion/mcp install
 ```
 
-Verify with:
+Verify the server registration with either:
+
+```bash
+hybridclaw gateway mcp list
+```
+
+or:
 
 ```text
 /mcp list
 ```
 
-Expected tools are typically:
+`mcp list` shows configured MCP servers, not the discovered tool names.
+HybridClaw merges MCP tools into the active session tool list at runtime, so the
+practical verification path is to run a prompt that should use the server and
+then inspect the response or the Datalion bridge log.
+
+In Datalion, "tab" and "dashboard" refer to the same report subpage entity.
+
+When the server is healthy, the active tool names are typically:
 
+- `datalion__list_projects`
+- `datalion__read_project`
 - `datalion__create_project`
+- `datalion__edit_project`
+- `datalion__list_data_sources`
 - `datalion__upload_data`
+- `datalion__import_excel_data`
+- `datalion__list_reports`
+- `datalion__create_report`
+- `datalion__create_report_tab`
+- `datalion__edit_report_tab`
+- `datalion__delete_report_tab`
+- `datalion__open_project_browser`
+- `datalion__open_report_browser`
+- `datalion__open_dashboard_browser`
+- `datalion__open_add_widget_browser`
 - `datalion__get_chart_table`
+- `datalion__list_codebook`
+- `datalion__download_codebook`
+- `datalion__generate_codebook`
+- `datalion__delete_codebook`
+- `datalion__upload_codebook`
+
+This is the current 22-tool bridge surface:
+
+- `project.list`, `project.read`, `project.create`, `project.edit`
+- `data.sources`, `data.upload`, `data.import.excel`
+- `report.list`, `report.create`, `report.tab.create`, `report.tab.edit`,
+  `report.tab.delete`
+- browser URL helpers:
+  - `open_project_browser`
+  - `open_report_browser`
+  - `open_dashboard_browser`
+  - `open_add_widget_browser`
+- `chart.table`
+- `codebook.list`, `codebook.download`, `codebook.generate`,
+  `codebook.delete`, `codebook.upload`
+
+## Testing the Skill
+
+For explicit TUI testing, use:
+
+```text
+/skill datalion create a new project named "MCP Smoke Test 2026-03-25"
+```
+
+That is the safest explicit invocation path in HybridClaw sessions.
+`/datalion ...` is not a built-in slash-menu entry, so it may not appear in
+autocomplete even though the skill itself is installed.
+
+## TUI Smoke Tests
+
+Use these in the TUI after `/mcp reconnect datalion`:
+
+```text
+/skill datalion list all projects
+```
+
+```text
+/skill datalion read project 123 and show its full details and defsettings
+```
+
+```text
+/skill datalion create a new project named "MCP Smoke Test 2026-03-25" with identcode "mcp-smoke-test-2026-03-25" and defsettings {"language":"en","themeselection":"default"}
+```
+
+```text
+/skill datalion create a report named "MCP Smoke Test Report" for project 123
+```
+
+```text
+/skill datalion create a new tab in report 456 for project 123 named "Executive Summary"
+```
+
+```text
+/skill datalion edit tab 456 in report 456 for project 123 by setting description to "Executive Summary - Revised" and sortorder to 2
+```
+
+```text
+/skill datalion delete tab 456 from report 456 for project 123
+```
+
+```text
+/skill datalion open project 123 in browser
+```
+
+```text
+/skill datalion open report 456 for project 123 in browser
+```
+
+```text
+/skill datalion open dashboard 789 for project 123 in browser
+```
+
+```text
+/skill datalion open the add-widget modal for project 123, div 4, and category 321
+```
+
+```text
+/skill datalion update project 123 by merging these defsettings: {"disp_precision":2,"omit_na":true,"report_instant_export":true}
+```
+
+```text
+/skill datalion list the data sources for project 123
+```
+
+```text
+/skill datalion import the workbook at /Users/bkoehler/Downloads/synthclaw_sales.xlsx into project 123 as the main data source using useDefaultDataSource=true and createCodebook=true
+```
+
+```text
+/skill datalion list the reports for project 123
+```
+
+```text
+/skill datalion create a report named "MCP Smoke Test Report" for project 123
+```
+
+```text
+/skill datalion download the codebook for project 123
+```
+
+```text
+/skill datalion list the question-level codebook categories for project 123
+```
+
+```text
+/skill datalion generate the codebook for project 123 from the current project data
+```
+
+```text
+/skill datalion delete the codebook for project 123 but keep textboxes
+```
+
+```text
+/skill datalion delete the codebook for project 123 and include textboxes
+```
+
+```text
+/skill datalion upload this codebook CSV to project 123 as "codebook.csv" using importType 2:
+variable,label,short_label,value
+q1,Overall satisfaction,Satisfaction,1
+q2,Recommend to a friend,Recommendation,1
+```
+
+```text
+/skill datalion upload this codebook CSV to project 123 as "codebook.csv" using importType 3 and columnMapping ["fieldname","label","category","values"]:
+variable,label,short_label,value
+q1,Overall satisfaction,Satisfaction,1
+q2,Recommend to a friend,Recommendation,1
+```
+
+Bridge-side confirmation is written to:
+
+- `/Users/bkoehler/src/datalion/mcp/mcp-bridge-debug.log`
+
+Look for `Received tools/call request` entries such as `list_projects`,
+`read_project`, `create_project`, `edit_project`, `list_data_sources`,
+`import_excel_data`, `list_reports`, `create_report`, `list_codebook`,
+`download_codebook`, `generate_codebook`, `delete_codebook`, and
+`upload_codebook`.
 
 ## Required Token Abilities
 
 The current backend checks these abilities:
 
+- `projects.read` for project listing and reads
 - `projects.create` for project creation
-- `data.upload` for data import
+- `projects.edit` for project settings updates
+- `data.read` for project data source reads
+- `data.upload` for CSV upload and excel import
+- `reports.read` for report listing
+- `reports.write` for report creation
 - `charts.view-api` for chart table reads
+- `codebook.read` for codebook downloads
+- `codebook.write` for codebook generation, deletion, and upload
 
 If a call fails with `403`, check the token abilities before retrying.
 
@@ -51,12 +241,31 @@ If a call fails with `403`, check the token abilities before retrying.
 
 | Task | Best path today | Notes |
 | --- | --- | --- |
-| Create project | `datalion__create_project` | Direct MCP support exists. The current backend creates the project from `name`; do not assume extra descriptive fields are persisted unless you verify it. |
+| List projects | `datalion__list_projects` | Direct MCP support exists. Returns `projectId`, `identcode`, `name`, `description`, `status`, and `source` for accessible projects. |
+| Read project | `datalion__read_project` | Direct MCP support exists. Returns full project details including `defsettings`, `categoriesCount`, and `dataSourcesCount`. |
+| Create project | `datalion__create_project` | Direct MCP support exists. The bridge advertises `name` and optional `identcode` and `defsettings`. DataLion uses `name` for project description and dtitle. |
+| Edit project settings | `datalion__edit_project` | Direct MCP support exists. `defsettings` must be an object and is merged into the existing project settings rather than replacing them wholesale. |
+| List data sources | `datalion__list_data_sources` | Direct MCP support exists. Returns each data source with `id`, `name`, `comment`, row count, and timestamps. |
 | Upload CSV data | `datalion__upload_data` | Best current MCP path. Confirm header, delimiter, encoding, truncate behavior, and target project ID. |
-| Upload Excel workbook | Convert to CSV first, then `datalion__upload_data`, or use UI/API fallback | The current bridge accepts a string payload, so CSV text is the reliable path. |
+| Import Excel or CSV with full pipeline | `datalion__import_excel_data` | Direct MCP support exists. Accepts `localPath` or base64 `file`, plus `filename` when needed; supports `dataSourceName`, `useDefaultDataSource`, `replaceData`, `runCalculations`, `convertComma`, `skipLines`, `createCodebook`, and `comment`. Use `useDefaultDataSource=true` when you want the workbook imported into the main project data table so codebook generation reads the same data table. |
+| Upload Excel workbook | `datalion__import_excel_data` | Preferred direct MCP path for `.xlsx` workbooks. Use `localPath` for a local file or base64 `file` if you already have the workbook bytes. If you want the main/default data source, set `useDefaultDataSource=true`. If you send base64 directly, also provide `filename`. |
+| List reports | `datalion__list_reports` | Direct MCP support exists. Returns report id, name, publish/archive flags, owner, and tab count. |
+| Create report | `datalion__create_report` | Direct MCP support exists. Requires `projectId` and report `name`. The report is seeded with a first tab and the response returns both IDs. |
+| Create report tab | `datalion__create_report_tab` | Direct MCP support exists. Requires `projectId`, `reportId`, and `description`. Optional tab/dashboard settings can be applied at creation time. |
+| Edit report tab | `datalion__edit_report_tab` | Direct MCP support exists. Requires `projectId` and `tabId`, then merges the supplied tab/dashboard fields. |
+| Delete report tab | `datalion__delete_report_tab` | Direct MCP support exists. Requires `projectId` and `tabId`. |
+| Open project in browser | `datalion__open_project_browser` | Bridge-local helper. Returns the project screen URL. |
+| Open report in browser | `datalion__open_report_browser` | Bridge-local helper. Returns the report editor URL, or the tab/dashboard URL when `tabId` is supplied. |
+| Open dashboard in browser | `datalion__open_dashboard_browser` | Bridge-local helper. Returns the tab/dashboard screen URL. |
+| Open add-widget modal | `datalion__open_add_widget_browser` | Bridge-local helper. Returns the chart-add modal URL for adding a question/widget to a tab/dashboard. |
 | Read chart table | `datalion__get_chart_table` | Requires `projectId` plus `chartId` when the chart ID does not already include the project prefix. Optional filters are passed through. |
+| List codebook categories | `datalion__list_codebook` | Direct MCP support exists. Returns question-level measure/item categories with `categoryImportId`, `label`, and `fieldname`. |
+| Download codebook | `datalion__download_codebook` | Direct MCP support exists. Returns the category tree plus a total count. |
+| Generate codebook | `datalion__generate_codebook` | Direct MCP support exists. Regenerates codebook categories from project data. |
+| Delete codebook | `datalion__delete_codebook` | Direct MCP support exists. Optional `includeTextboxes=true` expands the deletion to textboxes. |
+| Upload codebook CSV | `datalion__upload_codebook` | Direct MCP support exists. The bridge accepts raw CSV `data` or base64 `file`, plus `filename`, optional `importType` (`2` replace, `3` update, `4` append), and optional `columnMapping` as an array aligned to CSV column order. |
 | Create or update dashboard | REST `/api/v1/dashboards` or Datalion UI | Current MCP bridge does not expose dashboard CRUD. See `openapi.yaml` and `routes/dashboard.php`. |
-| Create or update report | REST `/api/v1/reports` or Datalion UI | Current MCP bridge does not expose report CRUD. |
+| Update report after creation | REST `/api/v1/reports` or Datalion UI | Current MCP bridge exposes report list/create and tab CRUD, but not full report CRUD. |
 | Generate exports | Browser/UI or export web routes | Export flows currently live in `routes/export.php` web routes rather than the MCP bridge. |
 
 ## Fallback Inspection Points