@hybridaione/hybridclaw 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 ## [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
+
+- **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
+
+- **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**: `/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)
 
 ### Added

package/README.md

@@ -24,6 +24,9 @@ agent reuse authenticated web sessions for later browser automation.
 Local plugins can extend the gateway with typed manifests, plugin tools,
 memory layers, prompt hooks, and lifecycle hooks, including the installable
 QMD-backed memory layer shipped in `plugins/qmd-memory`.
+Web chat and TUI can attach current-turn files, and inline context references
+like `@file:src/app.ts`, `@diff`, or `@url:https://example.com/spec` can
+ground a turn without pasting raw content.
 
 Operators can also health-check the runtime with `hybridclaw doctor`, tune
 skill availability globally or per channel, and review adaptive skill health
@@ -189,6 +192,9 @@ Examples:
 - `/model clear` removes the session override and falls back to the current agent model or the global default.
 - `/agent model <name>` sets the persistent model for the current session agent.
 - `/model info` shows the current model configuration by scope (global default, agent model, and any session override).
+- Use `HYBRIDAI_BASE_URL` to override `hybridai.baseUrl` for the current
+  process without rewriting `~/.hybridclaw/config.json`, which is useful for
+  local or preview HybridAI deployments.
 - Use `HYBRIDCLAW_CODEX_BASE_URL` to override the default Codex backend base URL (`https://chatgpt.com/backend-api/codex`).
 
 Runtime model:
@@ -268,6 +274,26 @@ hybridclaw browser reset
   local storage without exposing credentials in chat.
 - Treat the browser profile directory as sensitive operator data.
 
+## Context References And Attachments
+
+HybridClaw can ground a prompt with current-turn uploads or inline context
+references instead of making you paste large blobs manually.
+
+```text
+Explain this regression using @diff and @file:src/gateway/gateway.ts:120-220
+Compare @folder:docs/development with @url:https://example.com/spec
+```
+
+- Web chat accepts uploads and pasted clipboard items for images, audio, PDFs,
+  Office docs, and text files before send.
+- TUI queues a copied local file or clipboard image with `/paste` or `Ctrl-V`
+  before sending.
+- Inline references supported in prompts are `@file:path[:start-end]`,
+  `@folder:path`, `@diff`, `@staged`, `@git:<count>`, and
+  `@url:https://...`.
+- If a reference is blocked or too large, HybridClaw keeps the prompt text and
+  adds a warning instead of silently broadening access.
+
 ## Agent Packages
 
 HybridClaw can package an agent into a portable `.claw` archive for backup,
@@ -275,18 +301,20 @@ distribution, or bootstrap flows:
 
 ```bash
 hybridclaw agent list
-hybridclaw agent pack main -o /tmp/main.claw
+hybridclaw agent export main -o /tmp/main.claw
 hybridclaw agent inspect /tmp/main.claw
-hybridclaw agent unpack /tmp/main.claw --id demo-agent --yes
+hybridclaw agent install /tmp/main.claw --id demo-agent --yes
 ```
 
-- `agent pack` exports the workspace plus optional bundled workspace skills and
-  home plugins.
+- `agent export` exports the workspace plus optional bundled workspace skills
+  and home plugins.
 - `agent inspect` validates the manifest and prints archive metadata without
   extracting it.
-- `agent unpack` restores the agent, fills missing bootstrap files, and
+- `agent install` restores the agent, fills missing bootstrap files, and
   re-registers bundled content with the runtime.
-- See [docs/development/agent-packages.md](./docs/development/agent-packages.md)
+- Legacy aliases still work: `agent pack` maps to `export`, and `agent unpack`
+  maps to `install`.
+- See [docs/development/extensibility/agent-packages.md](./docs/development/extensibility/agent-packages.md)
   for the archive layout, manifest fields, and security rules.
 
 ## Local Provider Quickstart (LM Studio Example)
@@ -402,7 +430,7 @@ such as `filesystem__read_file` or `github__list_issues`.
 
 ## Bundled Skills
 
-HybridClaw currently ships with 28 bundled skills. Notable workflow and app
+HybridClaw currently ships with 27 bundled skills. Notable workflow and app
 integrations include:
 
 - `pdf` is bundled and supports text extraction, page rendering, fillable form inspection/filling, and non-fillable overlay workflows.
@@ -419,7 +447,6 @@ integrations include:
 - `github-pr-workflow` is bundled for branch creation, commits, PR authoring, CI follow-up, and merge-readiness workflows with GitHub.
 - `write-blog-post` is bundled for audience-aware blog post outlines and drafts built from briefs, notes, transcripts, or source material.
 - `discord` is bundled for Discord channel operations through the `message` tool, including reads, sends, reactions, pins, and threads.
-- `himalaya` is bundled for host-side IMAP/SMTP email workflows through the Himalaya CLI.
 - `google-workspace` is bundled for Gmail, Calendar, Drive, Docs, and Sheets setup guidance plus browser/API workflow coordination.
 - `1password` is bundled for secure `op`-based secret lookup and command injection workflows.
 - `stripe` is bundled for Stripe API, CLI, Dashboard, checkout, billing, and webhook-debugging workflows with a test-mode-first default.
@@ -428,11 +455,14 @@ integrations include:
 - `apple-passwords` is bundled for Passwords.app and Keychain-backed credential lookup on macOS.
 - `apple-music` is bundled for macOS Music app playback control, now-playing checks, and Apple Music URL workflows.
 - Use `hybridclaw skill list` to inspect available installers and `hybridclaw skill install pdf [install-id]` when a bundled skill advertises optional setup helpers.
+- Use `hybridclaw skill import official/himalaya` to install the packaged Himalaya community skill into `~/.hybridclaw/skills` for host-side IMAP/SMTP email workflows.
+- Use `hybridclaw skill import <source>` to install community skills into `~/.hybridclaw/skills` from `skills-sh/anthropics/skills/brand-guidelines`, `clawhub/brand-voice`, `lobehub/github-issue-helper`, `claude-marketplace/brand-guidelines@anthropic-agent-skills`, `well-known:https://mintlify.com/docs`, or explicit GitHub repo/path refs such as `anthropics/skills/skills/brand-guidelines`.
+- Use `hybridclaw skill import --force <source>` to override a `caution` scanner verdict for a reviewed community skill. `dangerous` verdicts stay blocked.
 
 Skills can be disabled globally or per channel kind (`discord`, `msteams`,
 `whatsapp`, `email`) with `hybridclaw skill enable|disable <name> [--channel <kind>]`
 or via the TUI `/skill config` screen. For observation-driven health and
-amendment workflows, use `hybridclaw skill inspect|runs|amend|history` or the
+amendment workflows, use `hybridclaw skill inspect|runs|learn|history` or the
 admin `Skills` page.
 
 ## Optional Office Dependencies
@@ -489,7 +519,7 @@ CLI runtime commands:
 - `hybridclaw gateway compact` — Archive older session history into semantic memory while preserving a recent active context tail
 - `hybridclaw gateway reset [yes|no]` — Clear session history, reset per-session model/chatbot/RAG settings, and remove the current agent workspace (confirmation required)
 - `hybridclaw agent list` — Show registered agents in a script-friendly tab-separated format
-- `hybridclaw agent export [agent-id] [-o <path>]`, `inspect <file.claw>`, `install <file.claw> [--id <id>]`, `uninstall <agent-id> [--yes]` — Manage portable `.claw` agent archives
+- `hybridclaw agent export [agent-id] [-o <path>]`, `inspect <file.claw>`, `install <file.claw> [--id <id>]`, `uninstall <agent-id> [--yes]` — Manage portable `.claw` agent archives (legacy `pack` / `unpack` aliases still work)
 - `hybridclaw tui` — Start terminal client connected to gateway
 - `hybridclaw tui --resume <sessionId>` / `hybridclaw --resume <sessionId>` — Resume an earlier TUI session by canonical session id
 - `hybridclaw onboarding` — Run trust-model acceptance plus interactive provider onboarding
@@ -502,9 +532,6 @@ CLI runtime commands:
 - `hybridclaw channels email setup [--address <email>] [--password <password>] [--imap-host <host>] [--imap-port <port>] [--imap-secure|--no-imap-secure] [--smtp-host <host>] [--smtp-port <port>] [--smtp-secure|--no-smtp-secure] [--folder <name>]... [--allow-from <email|*@domain|*>]... [--poll-interval-ms <ms>] [--text-chunk-limit <chars>] [--media-max-mb <mb>]` — Configure IMAP/SMTP email delivery, optionally prompt for missing credentials, default to a 30-second IMAP poll interval, and save `EMAIL_PASSWORD`
 - `hybridclaw channels whatsapp setup [--reset] [--allow-from <+E164>]...` — Prepare private-by-default WhatsApp config, enable the default `👀` ack reaction, optionally wipe stale auth, open a temporary pairing session, and print the QR code
 - `hybridclaw browser login [--url <url>]`, `status`, `reset` — Manage the persistent browser profile used for authenticated web automation
-- `hybridclaw agent list` — List registered agents in a script-friendly format
-- `hybridclaw agent pack [agent-id] [-o <path>] [--skills ...] [--plugins ...]` — Export a portable `.claw` archive with optional bundled skills and plugins
-- `hybridclaw agent inspect <file.claw>` / `unpack <file.claw> [--id <id>] [--force] [--skip-externals] [--yes]` — Validate or restore a packaged agent archive
 - `hybridclaw local status` — Show current local backend config and default model
 - `hybridclaw local configure <backend> <model-id> [--base-url <url>] [--api-key <key>] [--no-default]` — Enable and configure a local backend
 - `hybridclaw hybridai ...`, `hybridclaw codex ...`, and `hybridclaw local ...` — Legacy aliases for the older provider-specific command surface
@@ -512,7 +539,8 @@ CLI runtime commands:
 - `hybridclaw doctor [--fix|--json|<component>]` — Diagnose runtime, gateway, config, credentials, database, providers, local backends, Docker, channels, skills, security, and disk state
 - `hybridclaw skill list` — Show skills and any declared installer options
 - `hybridclaw skill enable <skill-name> [--channel <kind>]`, `disable`, `toggle` — Manage global and per-channel skill availability
-- `hybridclaw skill inspect <skill-name>` / `hybridclaw skill inspect --all`, `runs`, `amend`, `history` — Review adaptive skill health, observations, and amendment history
+- `hybridclaw skill inspect <skill-name>` / `hybridclaw skill inspect --all`, `runs`, `learn`, `history` — Review adaptive skill health, observations, and amendment history
+- `hybridclaw skill import [--force] <source>` — Import a packaged community skill with `official/<skill-name>` or a community skill from `skills-sh`, `clawhub`, `lobehub`, `claude-marketplace`, `well-known`, or an explicit GitHub repo/path into `~/.hybridclaw/skills`; `--force` only overrides `caution`, never `dangerous`
 - `hybridclaw skill install <skill> [install-id]` — Run a declared skill dependency installer
 - `hybridclaw plugin list` — Show discovered plugins, enabled state, registered tools/hooks, and load errors
 - `hybridclaw plugin config <plugin-id> [key] [value|--unset]` — Inspect or change one top-level `plugins.list[].config` override

package/community-skills/datalion/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: datalion
+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:
+    tags:
+      - datalion
+      - analytics
+      - dashboards
+      - reports
+      - data
+    related_skills:
+      - xlsx
+      - project-manager
+---
+
+# DataLion
+
+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
+
+1. Verify the `datalion` MCP server is enabled and inspect which
+   `datalion__*` tools are actually available in the current session.
+2. Use MCP first for supported actions.
+3. Do not invent Datalion MCP tools. If a matching tool is missing, switch to a
+   REST or browser/UI path from
+   [references/setup-and-capabilities.md](references/setup-and-capabilities.md).
+4. Read first, write second. Restate the exact target object and proposed
+   mutation before calling a write path.
+
+## 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 ready-to-paste CLI and TUI examples, dependency notes, and ability
+  requirements.
+
+## Working Rules
+
+- 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 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.
+- 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 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.
+
+## Current MCP Coverage
+
+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
+- 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 `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. 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
+
+1. Confirm `projectId`, `chartId`, and filters.
+2. Call `datalion__get_chart_table`.
+3. Summarize the result and surface obvious caveats.
+
+### 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
+   `routes/export.php` in the local Datalion checkout or use browser automation
+   against the Datalion UI.
+3. Prefer REST endpoints for API-backed CRUD and browser/UI paths for web-only
+   export flows.
+4. Be explicit about which path you chose and why.