diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 5ed5cf9..c5c96b2 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -48,9 +48,15 @@ jobs: git commit -m "style: auto-fix formatting [skip ci]" git push + - name: Validate docs.json + run: node -e "JSON.parse(require('fs').readFileSync('docs.json','utf8'))" + + - name: Check navigation sync + id: nav-sync + run: npm run lint:nav + - name: Check broken links id: broken-links - continue-on-error: true run: npx mint broken-links 2>&1 | tee broken-links.log - name: Check accessibility @@ -64,7 +70,7 @@ jobs: run: npx mint openapi-check api-reference/openapi.yaml 2>&1 | tee openapi.log - name: Report issues on PR - if: github.event_name == 'pull_request' && (steps.broken-links.outcome == 'failure' || steps.a11y.outcome == 'failure' || steps.openapi.outcome == 'failure') + if: always() && github.event_name == 'pull_request' && (steps.nav-sync.outcome == 'failure' || steps.broken-links.outcome == 'failure' || steps.a11y.outcome == 'failure' || steps.openapi.outcome == 'failure') uses: actions/github-script@v8 with: script: | @@ -75,6 +81,9 @@ jobs: const a11y = fs.existsSync('a11y.log') ? fs.readFileSync('a11y.log', 'utf8') : ''; const openapi = fs.existsSync('openapi.log') ? fs.readFileSync('openapi.log', 'utf8') : ''; + if ('${{ steps.nav-sync.outcome }}' === 'failure') { + body += '### Navigation Sync\nPages referenced in `docs.json` do not match files on disk. Run `npm run lint:nav` locally for details.\n\n'; + } if ('${{ steps.broken-links.outcome }}' === 'failure') { body += '### Broken Links\n```\n' + brokenLinks.slice(0, 2000) + '\n```\n\n'; } @@ -93,7 +102,7 @@ jobs: }); - name: Fail if validation errors - if: steps.broken-links.outcome == 'failure' || steps.a11y.outcome == 'failure' || steps.openapi.outcome == 'failure' + if: always() && (steps.nav-sync.outcome == 'failure' || steps.broken-links.outcome == 'failure' || steps.a11y.outcome == 'failure' || steps.openapi.outcome == 'failure') run: | echo "Validation failed. Check the logs above." exit 1 diff --git a/.husky/pre-push b/.husky/pre-push new file mode 100755 index 0000000..070805d --- /dev/null +++ b/.husky/pre-push @@ -0,0 +1,67 @@ +#!/bin/sh + +echo "Running pre-push validation..." +echo "" + +failed=0 + +# Navigation sync (fast, pure Node — run first) +echo "==> Checking navigation/file sync..." +if npm run lint:nav; then + echo " Navigation sync passed." +else + echo " Navigation sync FAILED." + failed=1 +fi + +echo "" + +# Run mint checks in parallel using background jobs +echo "==> Running link and accessibility checks in parallel..." + +tmpdir=$(mktemp -d) + +(npx mint broken-links > "$tmpdir/links.log" 2>&1; echo $? > "$tmpdir/links.exit") & +pid_links=$! + +(npx mint a11y > "$tmpdir/a11y.log" 2>&1; echo $? > "$tmpdir/a11y.exit") & +pid_a11y=$! + +# Wait for both to finish +wait $pid_links +wait $pid_a11y + +# Report results +links_exit=$(cat "$tmpdir/links.exit") +a11y_exit=$(cat "$tmpdir/a11y.exit") + +echo "" +echo "--- Broken Links ---" +if [ "$links_exit" -eq 0 ]; then + echo " Passed." +else + cat "$tmpdir/links.log" + echo " Broken links check FAILED." + failed=1 +fi + +echo "" +echo "--- Accessibility ---" +if [ "$a11y_exit" -eq 0 ]; then + echo " Passed." +else + cat "$tmpdir/a11y.log" + echo " Accessibility check FAILED." + failed=1 +fi + +# Cleanup +rm -rf "$tmpdir" + +echo "" +if [ "$failed" -ne 0 ]; then + echo "Pre-push validation FAILED. Push aborted." + exit 1 +fi + +echo "All pre-push checks passed." diff --git a/analyzers/rules/AL0052.mdx b/analyzers/rules/AL0052.mdx index 3d9acee..9271895 100644 --- a/analyzers/rules/AL0052.mdx +++ b/analyzers/rules/AL0052.mdx @@ -79,4 +79,4 @@ dotnet_diagnostic.AL0052.severity = error - [AL0044 - AotSafe code must not call RequiresDynamicCode methods](/analyzers/rules/AL0044) - [AL0053 - Unnecessary AotUnsafe attribute](/analyzers/rules/AL0053) -- [AotUnsafe attribute documentation](/utilities/aot-testing) +- AotUnsafe attribute documentation diff --git a/analyzers/rules/AL0053.mdx b/analyzers/rules/AL0053.mdx index d53d9fa..3cd2231 100644 --- a/analyzers/rules/AL0053.mdx +++ b/analyzers/rules/AL0053.mdx @@ -80,4 +80,4 @@ The analyzer recognizes these as legitimate reasons for `[AotUnsafe]`: - [AL0052 - AotSafe code must not call AotUnsafe code](/analyzers/rules/AL0052) - [AL0044 - AotSafe code must not call RequiresDynamicCode methods](/analyzers/rules/AL0044) -- [AotUnsafe attribute documentation](/utilities/aot-testing) +- AotUnsafe attribute documentation diff --git a/analyzers/rules/index.mdx b/analyzers/rules/index.mdx deleted file mode 100644 index b262872..0000000 --- a/analyzers/rules/index.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Analyzer Rules -description: Complete reference for all ANcpLua.Analyzers diagnostic rules -icon: 'shield-check' ---- - -ANcpLua.Analyzers provides 102 diagnostic rules and 2 refactorings for C# code quality, organized by category. - -## Design Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ------------------------------------------------------- | -| [AL0001](/analyzers/rules/AL0001) | Error | Prohibit reassignment of primary constructor params | -| [AL0002](/analyzers/rules/AL0002) | Warning | Don't repeat negated patterns | -| [AL0006](/analyzers/rules/AL0006) | Warning | Field name conflicts with primary constructor parameter | -| [AL0010](/analyzers/rules/AL0010) | Info | Type should be partial for source generator support | -| [AL0103](/analyzers/rules/AL0103) | Warning | Closed type hierarchy switch exhaustiveness | - -## Reliability Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ----------------------------------------- | -| [AL0003](/analyzers/rules/AL0003) | Error | Don't divide by constant zero | -| [AL0104](/analyzers/rules/AL0104) | Warning | Prefer 'await using' for IAsyncDisposable | - -## Usage Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | -------------------------------------------------- | -| [AL0004](/analyzers/rules/AL0004) | Warning | Use pattern matching for Span constant comparison | -| [AL0005](/analyzers/rules/AL0005) | Warning | Use SequenceEqual for Span non-constant comparison | -| [AL0007](/analyzers/rules/AL0007) | Error | GetSchema should be explicitly implemented | -| [AL0008](/analyzers/rules/AL0008) | Error | GetSchema must return null and not be abstract | -| [AL0009](/analyzers/rules/AL0009) | Error | Don't call IXmlSerializable.GetSchema | -| [AL0025](/analyzers/rules/AL0025) | Warning | Anonymous function can be made static | -| [AL0026](/analyzers/rules/AL0026) | Warning | Avoid legacy time APIs, use TimeProvider | -| [AL0027](/analyzers/rules/AL0027) | Warning | Avoid legacy JSON APIs, use System.Text.Json | - -## Threading Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ---------------------------------------------- | -| [AL0011](/analyzers/rules/AL0011) | Warning | Avoid lock keyword on non-Lock types (.NET 9+) | -| [AL0057](/analyzers/rules/AL0057) | Warning | Avoid async void methods | -| [AL0058](/analyzers/rules/AL0058) | Warning | Avoid lock on 'this' | -| [AL0059](/analyzers/rules/AL0059) | Warning | Avoid lock on typeof(T) | -| [AL0060](/analyzers/rules/AL0060) | Warning | Avoid lock on string | -| [AL0105](/analyzers/rules/AL0105) | Warning | Avoid blocking calls in async methods | - -## OpenTelemetry Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ---------------------------------------------------- | -| [AL0012](/analyzers/rules/AL0012) | Warning | Deprecated OTel semantic convention attribute | -| [AL0013](/analyzers/rules/AL0013) | Info | Missing telemetry schema URL | -| [AL0061](/analyzers/rules/AL0061) | Warning | Activity/Span missing semantic convention attributes | -| [AL0062](/analyzers/rules/AL0062) | Warning | Deprecated semantic convention | -| [AL0063](/analyzers/rules/AL0063) | Warning | ActivitySource should be registered with AddSource() | -| [AL0073](/analyzers/rules/AL0073) | Error | [Traced] requires non-empty ActivitySourceName | -| [AL0076](/analyzers/rules/AL0076) | Warning | Missing OpenTelemetry configuration | -| [AL0077](/analyzers/rules/AL0077) | Warning | Duplicate instrumentation detected | -| [AL0078](/analyzers/rules/AL0078) | Error | Invalid ActivitySource name | -| [AL0079](/analyzers/rules/AL0079) | Info | Manual span recommended | -| [AL0085](/analyzers/rules/AL0085) | Error | Invalid attribute value | -| [AL0086](/analyzers/rules/AL0086) | Warning | Incorrect attribute type | -| [AL0087](/analyzers/rules/AL0087) | Info | Prefer constant attribute | -| [AL0088](/analyzers/rules/AL0088) | Warning | Sensitive data in span attribute | -| [AL0089](/analyzers/rules/AL0089) | Warning | Missing OTLP configuration | -| [AL0090](/analyzers/rules/AL0090) | Warning | Uncompressed OTLP export | -| [AL0091](/analyzers/rules/AL0091) | Warning | Batch export disabled | -| [AL0092](/analyzers/rules/AL0092) | Info | Consider configuring sampling | -| [AL0093](/analyzers/rules/AL0093) | Warning | Missing resource attributes | - -## Style Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ------------------------------------------------- | -| [AL0014](/analyzers/rules/AL0014) | Warning | Prefer pattern matching for null/zero comparisons | -| [AL0015](/analyzers/rules/AL0015) | Info | Normalize null-guard style | -| [AL0016](/analyzers/rules/AL0016) | Info | Combine declaration with subsequent null-check | - -## Version Management Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ----------------------------------------------------- | -| [AL0017](/analyzers/rules/AL0017) | Warning | Hardcoded package version in Directory.Packages.props | -| [AL0018](/analyzers/rules/AL0018) | Warning | Version.props not imported in Directory.Build.props | -| [AL0019](/analyzers/rules/AL0019) | Warning | Undefined version variable | -| [AL0054](/analyzers/rules/AL0054) | Warning | Diagnostic missing from documentation | -| [AL0055](/analyzers/rules/AL0055) | Warning | Diagnostic missing from release notes | -| [AL0056](/analyzers/rules/AL0056) | Warning | Diagnostic documentation mismatch | - -## ASP.NET Core Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | --------------------------------------------------------------- | -| [AL0020](/analyzers/rules/AL0020) | Error | IFormCollection requires explicit [FromForm] attribute | -| [AL0021](/analyzers/rules/AL0021) | Error | Multiple structured form sources conflict | -| [AL0022](/analyzers/rules/AL0022) | Error | Mixed IFormCollection and DTO form binding unsupported | -| [AL0023](/analyzers/rules/AL0023) | Error | Type cannot be form-bound (abstract, interface, no constructor) | -| [AL0024](/analyzers/rules/AL0024) | Error | [FromForm] and [FromBody] conflict on same method | -| [AL0080](/analyzers/rules/AL0080) | Warning | Missing resilience configuration | -| [AL0081](/analyzers/rules/AL0081) | Warning | Missing health checks | -| [AL0084](/analyzers/rules/AL0084) | Warning | Missing service discovery | -| [AL0106](/analyzers/rules/AL0106) | Warning | Avoid Task.Run in ASP.NET Core handlers | - -## Roslyn Utilities Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ----------------------------------------------------------- | -| [AL0028](/analyzers/rules/AL0028) | Info | Use IsEqualTo instead of SymbolEqualityComparer.Equals | -| [AL0029](/analyzers/rules/AL0029) | Info | Use HasAttribute instead of GetAttributes() patterns | -| [AL0030](/analyzers/rules/AL0030) | Info | Use Implements/InheritsFrom instead of type hierarchy loops | -| [AL0031](/analyzers/rules/AL0031) | Info | Use IsMethodNamed/TryGetConstantValue extensions | -| [AL0032](/analyzers/rules/AL0032) | Info | Use OrEmpty() instead of null-coalescing | -| [AL0033](/analyzers/rules/AL0033) | Info | Use ToImmutableArrayOrEmpty() extension | -| [AL0034](/analyzers/rules/AL0034) | Info | Use WhereNotNull() instead of Where(x => x != null) | -| [AL0035](/analyzers/rules/AL0035) | Info | Use GetFullyQualifiedName/GetMetadataName() | -| [AL0036](/analyzers/rules/AL0036) | Warning | Use Guard.NotNull() instead of throw pattern | -| [AL0037](/analyzers/rules/AL0037) | Warning | Use TryParseInt32/Guid/etc. extensions | -| [AL0038](/analyzers/rules/AL0038) | Warning | Use GetOrNull/GetOrDefault instead of TryGetValue | -| [AL0039](/analyzers/rules/AL0039) | Warning | Use EqualsIgnoreCase/StartsWithOrdinal extensions | -| [AL0040](/analyzers/rules/AL0040) | Warning | Use GetConstructorArgument/GetNamedArgument extensions | -| [AL0045](/analyzers/rules/AL0045) | Warning | Use Guard.NotNullOrEmpty() | -| [AL0046](/analyzers/rules/AL0046) | Warning | Use Guard.NotNullOrWhiteSpace() | -| [AL0047](/analyzers/rules/AL0047) | Warning | Use Guard.NotZero() | -| [AL0048](/analyzers/rules/AL0048) | Warning | Use Guard.NotNegative() | -| [AL0049](/analyzers/rules/AL0049) | Warning | Use Guard.Positive() | -| [AL0050](/analyzers/rules/AL0050) | Warning | Use Guard.NotEmpty() for Guid | -| [AL0051](/analyzers/rules/AL0051) | Warning | Use Guard.DefinedEnum() | - -## GenAI Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | ---------------------------------------------- | -| [AL0064](/analyzers/rules/AL0064) | Warning | GenAI span missing required attributes | -| [AL0065](/analyzers/rules/AL0065) | Warning | Use gen_ai.client.token.usage histogram | -| [AL0066](/analyzers/rules/AL0066) | Warning | GenAI operation name should follow conventions | -| [AL0074](/analyzers/rules/AL0074) | Warning | Deprecated GenAI semantic convention | - -## Metrics Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | -------------------------------------------- | -| [AL0067](/analyzers/rules/AL0067) | Warning | Meter should be registered with AddMeter() | -| [AL0068](/analyzers/rules/AL0068) | Warning | Metric name should follow naming conventions | -| [AL0071](/analyzers/rules/AL0071) | Error | [Meter] class must be partial static | -| [AL0072](/analyzers/rules/AL0072) | Error | Metric method must be partial | -| [AL0075](/analyzers/rules/AL0075) | Warning | High-cardinality tag on metric | - -## Configuration Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | -------------------------------------------------- | -| [AL0069](/analyzers/rules/AL0069) | Warning | ServiceDefaults configuration incomplete | -| [AL0070](/analyzers/rules/AL0070) | Warning | Collector endpoint should use OTLP protocol | -| [AL0082](/analyzers/rules/AL0082) | Info | Consider using configuration for connection string | -| [AL0083](/analyzers/rules/AL0083) | Warning | Insecure endpoint | -| [AL0096](/analyzers/rules/AL0096) | Warning | Enable EventSourceSupport for AOT with telemetry | - -## AOT/Trim Safety Rules - -| Rule | Severity | Description | -| --------------------------------- | -------- | -------------------------------------------------------- | -| [AL0041](/analyzers/rules/AL0041) | Error | [AotTest]/[TrimTest] must return int | -| [AL0042](/analyzers/rules/AL0042) | Warning | [AotTest]/[TrimTest] should return 100 on success | -| [AL0043](/analyzers/rules/AL0043) | Warning | [TrimSafe] code must not call [RequiresUnreferencedCode] | -| [AL0044](/analyzers/rules/AL0044) | Warning | [AotSafe] code must not call [RequiresDynamicCode] | -| [AL0094](/analyzers/rules/AL0094) | Warning | Avoid 'dynamic' keyword in AOT | -| [AL0095](/analyzers/rules/AL0095) | Warning | Avoid Expression.Compile() in AOT | -| [AL0101](/analyzers/rules/AL0101) | Warning | Activator.CreateInstance is not AOT-safe | -| [AL0102](/analyzers/rules/AL0102) | Warning | Type.GetType with dynamic name is not AOT-safe | - -## Refactorings - -| Rule | Description | -| --------------------------------- | ------------------------- | -| [AR0001](/analyzers/rules/AR0001) | Snake Case To Pascal Case | -| [AR0002](/analyzers/rules/AR0002) | Make Static Lambda | - -## Configuration - -All rules can be configured via `.editorconfig`: - -```ini -[*.cs] -# Disable a rule -dotnet_diagnostic.AL0001.severity = none - -# Change severity -dotnet_diagnostic.AL0014.severity = warning - -# Enable OpenTelemetry rules as errors in production code -[src/**/*.cs] -dotnet_diagnostic.AL0012.severity = error -dotnet_diagnostic.AL0013.severity = warning - -# Relax ASP.NET Core rules in test projects -[tests/**/*.cs] -dotnet_diagnostic.AL0020.severity = none -``` - -## Rule Severity Levels - -| Severity | Build Behavior | Use For | -| -------- | --------------------- | ----------------------------------- | -| Error | Breaks build | Critical issues, runtime exceptions | -| Warning | Shows in build output | Important issues to address | -| Info | IDE only by default | Suggestions and improvements | -| None | Disabled | Rules not applicable to project | diff --git a/datzi/automation/README.md b/datzi/automation/README.md deleted file mode 100644 index c370f72..0000000 --- a/datzi/automation/README.md +++ /dev/null @@ -1,10 +0,0 @@ -| ID | Title | Slug | Summary | -| --------- | ----------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| DATZI-001 | Cron jobs (Gateway scheduler) | cron-jobs | Reference for the Gateway's built-in cron scheduler including schedules, payloads, delivery modes, CLI commands, and JSON tool-call shapes. | -| DATZI-002 | Cron vs Heartbeat: When to Use Each | cron-vs-heartbeat | Decision guide comparing cron jobs and heartbeats for scheduling, covering use cases, advantages, cost profiles, and how to combine both. | -| DATZI-003 | Gmail Pub/Sub -> Datzi | gmail-pubsub | Step-by-step guide to wiring Gmail watch notifications through Google Pub/Sub and gog into Datzi webhooks for email-triggered agent runs. | -| DATZI-004 | Hooks | hooks | Reference for Datzi's internal event-driven hook system including discovery, structure, event types, bundled hooks, and how to create custom hooks. | -| DATZI-005 | Automation troubleshooting | troubleshooting | Diagnostic guide for cron and heartbeat scheduler issues including common failure signatures, timezone gotchas, and command ladders. | -| DATZI-006 | Webhooks | webhook | Reference for the Gateway's HTTP webhook endpoint enabling external systems to trigger agent runs or system events via POST requests with token auth. | -| DATZI-007 | Auth monitoring | auth-monitoring | How to check OAuth credential expiry health via the CLI and optional scripts for phone and systemd-based auth monitoring workflows. | -| DATZI-008 | Polls | poll | How to send polls across WhatsApp, Discord, and MS Teams via CLI, Gateway RPC, or the agent message tool. | diff --git a/datzi/automation/auth-monitoring.mdx b/datzi/automation/auth-monitoring.mdx index 77602f9..0221535 100644 --- a/datzi/automation/auth-monitoring.mdx +++ b/datzi/automation/auth-monitoring.mdx @@ -7,8 +7,6 @@ summary: How to check OAuth credential expiry health via the CLI and optional sc tags: [auth, oauth, monitoring, systemd, termux, scripts, credentials] --- -# Auth Monitoring - # Auth monitoring Datzi exposes OAuth expiry health via `datzi models status`. Use that for diff --git a/datzi/automation/cron-jobs.mdx b/datzi/automation/cron-jobs.mdx index a19f6d2..13c3eae 100644 --- a/datzi/automation/cron-jobs.mdx +++ b/datzi/automation/cron-jobs.mdx @@ -7,11 +7,9 @@ summary: Reference for the Gateway's built-in cron scheduler including schedules tags: [cron, scheduler, heartbeat, delivery, webhook, isolated, main-session] --- -# Cron Jobs - # Cron jobs (Gateway scheduler) -> **Cron vs Heartbeat?** See [Cron vs Heartbeat](/automation/cron-vs-heartbeat) for guidance on when to use each. +> **Cron vs Heartbeat?** See [Cron vs Heartbeat](/datzi/automation/cron-vs-heartbeat) for guidance on when to use each. Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can optionally deliver output back to a chat. @@ -19,7 +17,7 @@ the right time, and can optionally deliver output back to a chat. If you want _"run this every morning"_ or _"poke the agent in 20 minutes"_, cron is the mechanism. -Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting) +Troubleshooting: [/automation/troubleshooting](/datzi/automation/troubleshooting) ## TL;DR @@ -68,7 +66,7 @@ datzi cron add \ ## Tool-call equivalents (Gateway cron tool) For the canonical JSON shapes and examples, -see [JSON schema for tool calls](/automation/cron-jobs#json-schema-for-tool-calls). +see [JSON schema for tool calls](/datzi/automation/cron-jobs#json-schema-for-tool-calls). ## Where cron jobs are stored @@ -146,7 +144,7 @@ They must use `payload.kind = "systemEvent"`. - `wakeMode: "next-heartbeat"`: event waits for the next scheduled heartbeat. This is the best fit when you want the normal heartbeat prompt + main-session context. -See [Heartbeat](/gateway/heartbeat). +See [Heartbeat](/datzi/gateway/heartbeat). #### Isolated jobs (dedicated cron sessions) @@ -541,7 +539,7 @@ datzi system event --mode now --text "Next heartbeat: check battery." - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove` - `cron.run` (force or due), `cron.runs` - For immediate system events without a job, use [`datzi system event`](/cli/system). + For immediate system events without a job, use `datzi system event`. ## Troubleshooting diff --git a/datzi/automation/cron-vs-heartbeat.mdx b/datzi/automation/cron-vs-heartbeat.mdx index 8eb9a7c..73eb102 100644 --- a/datzi/automation/cron-vs-heartbeat.mdx +++ b/datzi/automation/cron-vs-heartbeat.mdx @@ -7,8 +7,6 @@ summary: Decision guide comparing cron jobs and heartbeats for scheduling, cover tags: [cron, heartbeat, scheduler, decision-guide, cost, lobster] --- -# Cron vs Heartbeat - # Cron vs Heartbeat: When to Use Each Both heartbeats and cron jobs let you run tasks on a schedule. This guide helps you choose the right mechanism for your @@ -83,7 +81,7 @@ The agent reads this on each heartbeat and handles all items in one turn. } ``` -See [Heartbeat](/gateway/heartbeat) for full configuration. +See [Heartbeat](/datzi/gateway/heartbeat) for full configuration. ## Cron: Precise Scheduling @@ -141,7 +139,7 @@ datzi cron add \ --delete-after-run ``` -See [Cron jobs](/automation/cron-jobs) for full CLI reference. +See [Cron jobs](/datzi/automation/cron-jobs) for full CLI reference. ## Decision Flowchart @@ -227,7 +225,7 @@ For ad-hoc workflows, call Lobster directly. - The tool is an **optional plugin**; enable it additively via `tools.alsoAllow: ["lobster"]` (recommended). - Lobster expects the `lobster` CLI to be available on `PATH`. -See [Lobster](/tools/lobster) for full usage and examples. +See Lobster for full usage and examples. ## Main Session vs Isolated Session @@ -295,6 +293,6 @@ datzi cron add \ ## Related -- [Heartbeat](/gateway/heartbeat) - full heartbeat configuration -- [Cron jobs](/automation/cron-jobs) - full cron CLI and API reference -- [System](/cli/system) - system events + heartbeat controls +- [Heartbeat](/datzi/gateway/heartbeat) - full heartbeat configuration +- [Cron jobs](/datzi/automation/cron-jobs) - full cron CLI and API reference +- System - system events + heartbeat controls diff --git a/datzi/automation/gmail-pubsub.mdx b/datzi/automation/gmail-pubsub.mdx index e56aab4..65dbcda 100644 --- a/datzi/automation/gmail-pubsub.mdx +++ b/datzi/automation/gmail-pubsub.mdx @@ -7,8 +7,6 @@ summary: Step-by-step guide to wiring Gmail watch notifications through Google P tags: [gmail, pubsub, webhook, google-cloud, tailscale, gog, hooks] --- -# Gmail PubSub - # Gmail Pub/Sub -> Datzi Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Datzi webhook. @@ -17,7 +15,7 @@ Goal: Gmail watch -> Pub/Sub push -> `gog gmail watch serve` -> Datzi webhook. - `gcloud` installed and logged in ([install guide](https://docs.cloud.google.com/sdk/docs/install-sdk)). - `gog` (gogcli) installed and authorized for the Gmail account ([gogcli.sh](https://gogcli.sh/)). -- Datzi hooks enabled (see [Webhooks](/automation/webhook)). +- Datzi hooks enabled (see [Webhooks](/datzi/automation/webhook)). - `tailscale` logged in ([tailscale.com](https://tailscale.com/)). Supported setup uses Tailscale Funnel for the public HTTPS endpoint. Other tunnel services can work, but are DIY/unsupported and require manual wiring. @@ -94,7 +92,7 @@ Notes: To disable (dangerous), set `hooks.gmail.allowUnsafeExternalContent: true`. To customize payload handling further, add `hooks.mappings` or a JS/TS transform module -under `~/.datzi/hooks/transforms` (see [Webhooks](/automation/webhook)). +under `~/.datzi/hooks/transforms` (see [Webhooks](/datzi/automation/webhook)). ## Wizard (recommended) diff --git a/datzi/automation/hooks.mdx b/datzi/automation/hooks.mdx index 4d3959d..88d2246 100644 --- a/datzi/automation/hooks.mdx +++ b/datzi/automation/hooks.mdx @@ -19,8 +19,6 @@ tags: # Hooks -# Hooks - Hooks provide an extensible event-driven system for automating actions in response to agent commands and events. Hooks are automatically discovered from directories and can be managed via CLI commands, similar to how skills work in Datzi. @@ -31,9 +29,9 @@ Hooks are small scripts that run when something happens. There are two kinds: - **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events. - **Webhooks**: external HTTP webhooks that let other systems trigger work in Datzi. - See [Webhook Hooks](/automation/webhook) or use `datzi webhooks` for Gmail helper commands. + See [Webhook Hooks](/datzi/automation/webhook) or use `datzi webhooks` for Gmail helper commands. -Hooks can also be bundled inside plugins; see [Plugins](/tools/plugin#plugin-hooks). +Hooks can also be bundled inside plugins; see [Plugins](/datzi/tools/skills). Common uses: @@ -379,7 +377,7 @@ them. - **`tool_result_persist`**: transform tool results before they are written to the session transcript. Must be synchronous; return the updated tool result payload or `undefined` to keep it as-is. - See [Agent Loop](/concepts/agent-loop). + See [Agent Loop](/datzi/concepts/agent-loop). ### Future Events @@ -1058,7 +1056,7 @@ node -e "import('./path/to/handler.ts').then(console.log)" ## See Also -- [CLI Reference: hooks](/cli/hooks) -- [Bundled Hooks README](https://github.com/datzi/datzi/tree/main/src/hooks/bundled) -- [Webhook Hooks](/automation/webhook) -- [Configuration](/gateway/configuration#hooks) +- CLI Reference: hooks +- [Bundled Hooks README](https://github.com/datzi/tree/main/src/hooks/bundled) +- [Webhook Hooks](/datzi/automation/webhook) +- [Configuration](/datzi/gateway/configuration#hooks) diff --git a/datzi/automation/poll.mdx b/datzi/automation/poll.mdx index c585970..be295e8 100644 --- a/datzi/automation/poll.mdx +++ b/datzi/automation/poll.mdx @@ -9,8 +9,6 @@ tags: [poll, whatsapp, discord, msteams, message, cli] # Polls -# Polls - ## Supported channels - WhatsApp (web channel) diff --git a/datzi/automation/troubleshooting.mdx b/datzi/automation/troubleshooting.mdx index 2e8340a..ca578ff 100644 --- a/datzi/automation/troubleshooting.mdx +++ b/datzi/automation/troubleshooting.mdx @@ -7,8 +7,6 @@ summary: Diagnostic guide for cron and heartbeat scheduler issues including comm tags: [troubleshooting, cron, heartbeat, delivery, timezone, diagnostics] --- -# Automation Troubleshooting - # Automation troubleshooting Use this page for scheduler and delivery issues (`cron` + `heartbeat`). @@ -121,7 +119,7 @@ Common signatures: Related: -- [/automation/cron-jobs](/automation/cron-jobs) -- [/gateway/heartbeat](/gateway/heartbeat) -- [/automation/cron-vs-heartbeat](/automation/cron-vs-heartbeat) -- [/concepts/timezone](/concepts/timezone) +- [/automation/cron-jobs](/datzi/automation/cron-jobs) +- [/gateway/heartbeat](/datzi/gateway/heartbeat) +- [/automation/cron-vs-heartbeat](/datzi/automation/cron-vs-heartbeat) +- /concepts/timezone diff --git a/datzi/automation/webhook.mdx b/datzi/automation/webhook.mdx index fb3e6bb..fbf692a 100644 --- a/datzi/automation/webhook.mdx +++ b/datzi/automation/webhook.mdx @@ -9,8 +9,6 @@ tags: [webhook, http, hooks, agent, session, security, gmail, delivery] # Webhooks -# Webhooks - Gateway can expose a small HTTP webhook endpoint for external triggers. ## Enable @@ -173,7 +171,7 @@ Mapping options (summary): - `allowUnsafeExternalContent: true` disables the external content safety wrapper for that hook (dangerous; only for trusted internal sources). - `datzi webhooks gmail setup` writes `hooks.gmail` config for `datzi webhooks gmail run`. - See [Gmail Pub/Sub](/automation/gmail-pubsub) for the full Gmail watch flow. + See [Gmail Pub/Sub](/datzi/automation/gmail-pubsub) for the full Gmail watch flow. ## Responses diff --git a/datzi/channels/README.md b/datzi/channels/README.md deleted file mode 100644 index 5ec6e1f..0000000 --- a/datzi/channels/README.md +++ /dev/null @@ -1,14 +0,0 @@ -| ID | Title | Slug | Summary | -| --------- | ------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| DATZI-020 | Broadcast Groups | broadcast-groups | How to configure multiple agents to process and respond to the same WhatsApp message simultaneously using broadcast groups with parallel or sequential strategies. | -| DATZI-021 | Channels & routing | channel-routing | How Datzi routes inbound messages to agents using deterministic rules including session key shapes, binding precedence, broadcast groups, and storage layout. | -| DATZI-022 | Discord (Bot API) | discord | Setup and configuration guide for the Discord Bot API channel including bot creation, guild policies, interactive components, voice channels, and troubleshooting. | -| DATZI-023 | Group messages (WhatsApp web channel) | group-messages | WhatsApp-specific behavior for group chats including activation modes, mention detection, context injection, and per-group session management. | -| DATZI-024 | Groups | groups | Cross-channel reference for group chat behavior in Datzi covering group policy, mention gating, session isolation, tool restrictions, and allowlists across all supported channels. | -| DATZI-025 | iMessage (legacy: imsg) | imessage | Legacy iMessage integration via the imsg CLI over JSON-RPC including setup, access control, deployment patterns, and troubleshooting; new setups should use BlueBubbles. | -| DATZI-026 | Chat Channels | index | Overview of all messaging channels supported by Datzi including WhatsApp, Telegram, Discord, Slack, Signal, iMessage, and many plugin-based channels. | -| DATZI-027 | Pairing | pairing | Explains Datzi's explicit owner-approval pairing system for both DM access control and node/device pairing including CLI commands and storage locations. | -| DATZI-028 | Slack | slack | Setup and configuration guide for the Slack channel covering Socket Mode and HTTP Events API, DM/channel policies, slash commands, threading, streaming, and manifest examples. | -| DATZI-029 | Telegram (Bot API) | telegram | Setup and configuration guide for the Telegram Bot API channel covering bot creation, DM/group policies, forum topics, streaming, inline buttons, stickers, and webhook mode. | -| DATZI-030 | Channel troubleshooting | troubleshooting | Cross-channel diagnostic guide with failure signature tables for WhatsApp, Telegram, Discord, Slack, iMessage, BlueBubbles, Signal, and Matrix. | -| DATZI-031 | WhatsApp (Web channel) | whatsapp | Setup and configuration guide for the WhatsApp channel via Baileys including QR pairing, access policies, group handling, media, ack reactions, and multi-account support. | diff --git a/datzi/channels/broadcast-groups.mdx b/datzi/channels/broadcast-groups.mdx index 69289f6..198334a 100644 --- a/datzi/channels/broadcast-groups.mdx +++ b/datzi/channels/broadcast-groups.mdx @@ -18,8 +18,6 @@ tags: # Broadcast Groups -# Broadcast Groups - **Status:** Experimental\ **Version:** Added in 2026.1.9 @@ -499,6 +497,6 @@ Planned features: ## See Also -- [Multi-Agent Configuration](/tools/multi-agent-sandbox-tools) -- [Routing Configuration](/channels/channel-routing) -- [Session Management](/concepts/sessions) +- [Multi-Agent Configuration](/datzi/tools/subagents) +- [Routing Configuration](/datzi/channels/channel-routing) +- [Session Management](/datzi/concepts/session) diff --git a/datzi/channels/channel-routing.mdx b/datzi/channels/channel-routing.mdx index 5bedfa4..2a80bd7 100644 --- a/datzi/channels/channel-routing.mdx +++ b/datzi/channels/channel-routing.mdx @@ -7,8 +7,6 @@ summary: How Datzi routes inbound messages to agents using deterministic rules i tags: [routing, channels, bindings, session-keys, agents, multi-agent, webchat] --- -# Channel Routing - # Channels & routing Datzi routes replies **back to the channel where a message came from**. The @@ -78,7 +76,7 @@ Config: } ``` -See: [Broadcast Groups](/channels/broadcast-groups). +See: [Broadcast Groups](/datzi/channels/broadcast-groups). ## Config overview diff --git a/datzi/channels/discord.mdx b/datzi/channels/discord.mdx index 79a82c2..a5fb67e 100644 --- a/datzi/channels/discord.mdx +++ b/datzi/channels/discord.mdx @@ -18,22 +18,20 @@ tags: ] --- -# Discord - # Discord (Bot API) Status: ready for DMs and guild channels via the official Discord gateway. - + Discord DMs default to pairing mode. - + Native command behavior and command catalog. - + Cross-channel diagnostics and repair flow. @@ -427,7 +425,7 @@ Use `bindings[].match.roles` to route Discord guild members to different agents - `commands.native=false` explicitly clears previously registered Discord native commands. - Native command auth uses the same Discord allowlists/policies as normal message handling. -See [Slash commands](/tools/slash-commands) for command catalog and behavior. +See [Slash commands](/datzi/tools/slash-commands) for command catalog and behavior. ## Voice channels @@ -498,8 +496,8 @@ Default gate behavior: ## Related -- [Pairing](/channels/pairing) -- [Channel routing](/channels/channel-routing) -- [Multi-agent routing](/concepts/multi-agent) -- [Troubleshooting](/channels/troubleshooting) -- [Slash commands](/tools/slash-commands) +- [Pairing](/datzi/channels/pairing) +- [Channel routing](/datzi/channels/channel-routing) +- [Multi-agent routing](/datzi/concepts/multi-agent) +- [Troubleshooting](/datzi/channels/troubleshooting) +- [Slash commands](/datzi/tools/slash-commands) diff --git a/datzi/channels/group-messages.mdx b/datzi/channels/group-messages.mdx deleted file mode 100644 index 25f4412..0000000 --- a/datzi/channels/group-messages.mdx +++ /dev/null @@ -1,126 +0,0 @@ ---- -id: DATZI-023 -category: channels -slug: group-messages -title: Group messages (WhatsApp web channel) -summary: WhatsApp-specific behavior for group chats including activation modes, mention detection, context injection, and per-group session management. -tags: - [ - whatsapp, - groups, - mention, - activation, - session, - context-injection, - group-chat - ] ---- - -# Group Messages - -# Group messages (WhatsApp web channel) - -Goal: let Datzi sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM -session. - -Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/Slack/iMessage as well; this doc focuses -on WhatsApp-specific behavior. For multi-agent setups, set `agents.list[].groupChat.mentionPatterns` per agent (or use -`messages.groupChat.mentionPatterns` as a global fallback). - -## What's implemented (2025-12-03) - -- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via - `mentionedJids`, regex patterns, or the bot's E.164 anywhere in the text). `always` wakes the agent on every message - but it should reply only when it can add meaningful value; otherwise it returns the silent token `NO_REPLY`. Defaults - can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When - `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all). -- Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted ( - `open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit - `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders). -- Per-group sessions: session keys look like `agent::whatsapp:group:` so commands such as `/verbose on` or - `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are - skipped for group threads. -- Context injection: **pending-only** group messages (default 50) that _did not_ trigger a run are prefixed under - `[Chat messages since your last reply - for context]`, with the triggering line under - `[Current message - respond to this]`. Messages already in the session are not re-injected. -- Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking. -- Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger. -- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a - short blurb into the system prompt like - `You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` - If metadata isn't available we still tell the agent it's a group chat. - -## Config example (WhatsApp) - -Add a `groupChat` block to `~/.datzi/datzi.json` so display-name pings work even when WhatsApp strips the visual -`@` in the text body: - -```json5 -{ - channels: { - whatsapp: { - groups: { - '*': { - requireMention: true - } - } - } - }, - agents: { - list: [ - { - id: 'main', - groupChat: { - historyLimit: 50, - mentionPatterns: ['@?datzi', '\\+?15555550123'] - } - } - ] - } -} -``` - -Notes: - -- The regexes are case-insensitive; they cover a display-name ping like `@datzi` and the raw number with or without - `+`/spaces. -- WhatsApp still sends canonical mentions via `mentionedJids` when someone taps the contact, so the number fallback is - rarely needed but is a useful safety net. - -### Activation command (owner-only) - -Use the group chat command: - -- `/activation mention` -- `/activation always` - -Only the owner number (from `channels.whatsapp.allowFrom`, or the bot's own E.164 when unset) can change this. Send -`/status` as a standalone message in the group to see the current activation mode. - -## How to use - -1. Add your WhatsApp account (the one running Datzi) to the group. -2. Say `@datzi …` (or include the number). Only allowlisted senders can trigger it unless you set - `groupPolicy: "open"`. -3. The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right - person. -4. Session-level directives (`/verbose on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group's - session; send them as standalone messages so they register. Your personal DM session remains independent. - -## Testing / verification - -- Manual smoke: - - Send an `@datzi` ping in the group and confirm a reply that references the sender name. - - Send a second ping and verify the history block is included then cleared on the next turn. -- Check gateway logs (run with `--verbose`) to see `inbound web message` entries showing `from: ` and the - `[from: …]` suffix. - -## Known considerations - -- Heartbeats are intentionally skipped for groups to avoid noisy broadcasts. -- Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first - will get a response. -- Session store entries will appear as `agent::whatsapp:group:` in the session store ( - `~/.datzi/agents//sessions/sessions.json` by default); a missing entry just means the group hasn't - triggered a run yet. -- Typing indicators in groups follow `agents.defaults.typingMode` (default: `message` when unmentioned). diff --git a/datzi/channels/groups.mdx b/datzi/channels/groups.mdx index ec34386..7a0ece5 100644 --- a/datzi/channels/groups.mdx +++ b/datzi/channels/groups.mdx @@ -22,8 +22,6 @@ tags: # Groups -# Groups - Datzi treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams. @@ -85,7 +83,7 @@ This gives you one agent "brain" (shared workspace + memory), but two execution - **Groups**: sandbox + restricted tools (Docker) > If you need truly separate workspaces/personas ("personal" and "public" must never mix), use a second agent + -> bindings. See [Multi-Agent Routing](/concepts/multi-agent). +> bindings. See [Multi-Agent Routing](/datzi/concepts/multi-agent). Example (DMs on host, groups sandboxed + messaging-only tools): @@ -421,4 +419,4 @@ like a human, avoid Markdown tables, and avoid typing literal `\n` sequences. ## WhatsApp specifics -See [Group messages](/channels/group-messages) for WhatsApp-only behavior (history injection, mention handling details). +See [Group messages](/datzi/channels/groups) for WhatsApp-only behavior (history injection, mention handling details). diff --git a/datzi/channels/imessage.mdx b/datzi/channels/imessage.mdx index 677b471..7faf0ec 100644 --- a/datzi/channels/imessage.mdx +++ b/datzi/channels/imessage.mdx @@ -7,12 +7,10 @@ summary: Legacy iMessage integration via the imsg CLI over JSON-RPC including se tags: [imessage, imsg, macos, legacy, pairing, groups, attachments, ssh, tailscale] --- -# iMessage - # iMessage (legacy: imsg) - For new iMessage deployments, use BlueBubbles. + For new iMessage deployments, use BlueBubbles. The `imsg` integration is legacy and may be removed in a future release. @@ -212,7 +210,7 @@ Disable: ## Configuration reference pointers -- [Configuration reference - iMessage](/gateway/configuration-reference#imessage) -- [Gateway configuration](/gateway/configuration) -- [Pairing](/channels/pairing) -- [BlueBubbles](/channels/bluebubbles) +- [Configuration reference - iMessage](/datzi/gateway/configuration-reference#imessage) +- [Gateway configuration](/datzi/gateway/configuration) +- [Pairing](/datzi/channels/pairing) +- BlueBubbles (see the channels overview for details) diff --git a/datzi/channels/index.mdx b/datzi/channels/index.mdx index d007ca4..5ed4cf4 100644 --- a/datzi/channels/index.mdx +++ b/datzi/channels/index.mdx @@ -19,8 +19,6 @@ tags: ] --- -# Chat Channels Index - # Chat Channels Datzi can talk to you on any chat app you already use. Each channel connects via the Gateway. @@ -28,37 +26,35 @@ Text is supported everywhere; media and reactions vary by channel. ## Supported channels -- [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing. -- [Telegram](/channels/telegram) — Bot API via grammY; supports groups. -- [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs. -- [IRC](/channels/irc) — Classic IRC servers; channels + DMs with pairing/allowlist controls. -- [Slack](/channels/slack) — Bolt SDK; workspace apps. -- [Feishu](/channels/feishu) — Feishu/Lark bot via WebSocket (plugin, installed separately). -- [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook. -- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately). -- [Signal](/channels/signal) — signal-cli; privacy-focused. -- [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with - full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe). -- [iMessage (legacy)](/channels/imessage) — Legacy macOS integration via imsg CLI (deprecated, use BlueBubbles for new +- [WhatsApp](/datzi/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing. +- [Telegram](/datzi/channels/telegram) — Bot API via grammY; supports groups. +- [Discord](/datzi/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs. +- [Slack](/datzi/channels/slack) — Bolt SDK; workspace apps. +- [iMessage (legacy)](/datzi/channels/imessage) — Legacy macOS integration via imsg CLI (deprecated, use BlueBubbles for new setups). -- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately). -- [LINE](/channels/line) — LINE Messaging API bot (plugin, installed separately). -- [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately). -- [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately). -- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately). -- [Tlon](/channels/tlon) — Urbit-based messenger (plugin, installed separately). -- [Twitch](/channels/twitch) — Twitch chat via IRC connection (plugin, installed separately). -- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately). -- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (plugin, installed separately). -- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket. +- IRC — Classic IRC servers; channels + DMs with pairing/allowlist controls. +- Feishu — Feishu/Lark bot via WebSocket (plugin, installed separately). +- Google Chat — Google Chat API app via HTTP webhook. +- Mattermost — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately). +- Signal — signal-cli; privacy-focused. +- BlueBubbles — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with + full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe). +- Microsoft Teams — Bot Framework; enterprise support (plugin, installed separately). +- LINE — LINE Messaging API bot (plugin, installed separately). +- Nextcloud Talk — Self-hosted chat via Nextcloud Talk (plugin, installed separately). +- Matrix — Matrix protocol (plugin, installed separately). +- Nostr — Decentralized DMs via NIP-04 (plugin, installed separately). +- Tlon — Urbit-based messenger (plugin, installed separately). +- Twitch — Twitch chat via IRC connection (plugin, installed separately). +- Zalo — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately). +- Zalo Personal — Zalo personal account via QR login (plugin, installed separately). ## Notes - Channels can run simultaneously; configure multiple and Datzi will route per chat. - Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and stores more state on disk. -- Group behavior varies by channel; see [Groups](/channels/groups). -- DM pairing and allowlists are enforced for safety; see [Security](/gateway/security). -- Telegram internals: [grammY notes](/channels/grammy). -- Troubleshooting: [Channel troubleshooting](/channels/troubleshooting). -- Model providers are documented separately; see [Model Providers](/providers/models). +- Group behavior varies by channel; see [Groups](/datzi/channels/groups). +- DM pairing and allowlists are enforced for safety; see [Security](/datzi/gateway/authentication). +- Troubleshooting: [Channel troubleshooting](/datzi/channels/troubleshooting). +- Model providers are documented separately; see [Model Providers](/datzi/concepts/model-providers). diff --git a/datzi/channels/pairing.mdx b/datzi/channels/pairing.mdx index 025443f..55e58b7 100644 --- a/datzi/channels/pairing.mdx +++ b/datzi/channels/pairing.mdx @@ -21,22 +21,20 @@ tags: # Pairing -# Pairing - "Pairing" is Datzi's explicit **owner approval** step. It is used in two places: 1. **DM pairing** (who is allowed to talk to the bot) 2. **Node pairing** (which devices/nodes are allowed to join the gateway network) -Security context: [Security](/gateway/security) +Security context: [Security](/datzi/gateway/authentication) ## 1) DM pairing (inbound chat access) When a channel is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve. -Default DM policies are documented in: [Security](/gateway/security) +Default DM policies are documented in: [Security](/datzi/gateway/authentication) Pairing codes: @@ -109,13 +107,11 @@ Stored under `~/.datzi/devices/`: ## Related docs -- Security model + prompt injection: [Security](/gateway/security) -- Updating safely (run doctor): [Updating](/install/updating) +- Security model + prompt injection: [Security](/datzi/gateway/authentication) +- Updating safely (run doctor): [Updating](/datzi/install/updating) - Channel configs: - - Telegram: [Telegram](/channels/telegram) - - WhatsApp: [WhatsApp](/channels/whatsapp) - - Signal: [Signal](/channels/signal) - - BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles) - - iMessage (legacy): [iMessage](/channels/imessage) - - Discord: [Discord](/channels/discord) - - Slack: [Slack](/channels/slack) + - Telegram: [Telegram](/datzi/channels/telegram) + - WhatsApp: [WhatsApp](/datzi/channels/whatsapp) + - iMessage (legacy): [iMessage](/datzi/channels/imessage) + - Discord: [Discord](/datzi/channels/discord) + - Slack: [Slack](/datzi/channels/slack) diff --git a/datzi/channels/slack.mdx b/datzi/channels/slack.mdx index 57fa1f6..f23d943 100644 --- a/datzi/channels/slack.mdx +++ b/datzi/channels/slack.mdx @@ -20,8 +20,6 @@ tags: # Slack -# Slack - Status: production-ready for DMs + channels via Slack app integrations. Default mode is Socket Mode; HTTP Events API mode is also supported. @@ -350,8 +348,8 @@ channels: ## Related -- [Pairing](/channels/pairing) -- [Channel routing](/channels/channel-routing) -- [Troubleshooting](/channels/troubleshooting) -- [Configuration](/gateway/configuration) -- [Slash commands](/tools/slash-commands) +- [Pairing](/datzi/channels/pairing) +- [Channel routing](/datzi/channels/channel-routing) +- [Troubleshooting](/datzi/channels/troubleshooting) +- [Configuration](/datzi/gateway/configuration) +- [Slash commands](/datzi/tools/slash-commands) diff --git a/datzi/channels/telegram.mdx b/datzi/channels/telegram.mdx index 17ef6ad..9150077 100644 --- a/datzi/channels/telegram.mdx +++ b/datzi/channels/telegram.mdx @@ -20,8 +20,6 @@ tags: ] --- -# Telegram - # Telegram (Bot API) Status: production-ready for bot DMs + groups via grammY. Long polling is the default mode; webhook mode is optional. @@ -372,7 +370,7 @@ Default local listener for webhook mode binds to `127.0.0.1:8787`. ## Related -- [Pairing](/channels/pairing) -- [Channel routing](/channels/channel-routing) -- [Multi-agent routing](/concepts/multi-agent) -- [Troubleshooting](/channels/troubleshooting) +- [Pairing](/datzi/channels/pairing) +- [Channel routing](/datzi/channels/channel-routing) +- [Multi-agent routing](/datzi/concepts/multi-agent) +- [Troubleshooting](/datzi/channels/troubleshooting) diff --git a/datzi/channels/troubleshooting.mdx b/datzi/channels/troubleshooting.mdx index dfef02b..fa51a40 100644 --- a/datzi/channels/troubleshooting.mdx +++ b/datzi/channels/troubleshooting.mdx @@ -19,8 +19,6 @@ tags: ] --- -# Channel Troubleshooting - # Channel troubleshooting Use this page when a channel connects but behavior is wrong. @@ -53,7 +51,7 @@ Healthy baseline: | Group messages ignored | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. | | Random disconnect/relogin loops | `datzi channels status --probe` + logs | Re-login and verify credentials directory is healthy. | -Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick) +Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/datzi/channels/whatsapp#troubleshooting-quick) ## Telegram @@ -66,7 +64,7 @@ Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whats | Send failures with network errors | Inspect logs for Telegram API call failures | Fix DNS/IPv6/proxy routing to `api.telegram.org`. | | Upgraded and allowlist blocks you | `datzi security audit` and config allowlists | Run `datzi doctor --fix` or replace `@username` with numeric sender IDs. | -Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) +Full troubleshooting: [/channels/telegram#troubleshooting](/datzi/channels/telegram#troubleshooting) ## Discord @@ -78,7 +76,7 @@ Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#tr | Group messages ignored | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. | | DM replies missing | `datzi pairing list discord` | Approve DM pairing or adjust DM policy. | -Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) +Full troubleshooting: [/channels/discord#troubleshooting](/datzi/channels/discord#troubleshooting) ## Slack @@ -90,7 +88,7 @@ Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#trou | DMs blocked | `datzi pairing list slack` | Approve pairing or relax DM policy. | | Channel message ignored | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`. | -Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) +Full troubleshooting: [/channels/slack#troubleshooting](/datzi/channels/slack#troubleshooting) ## iMessage and BlueBubbles @@ -104,8 +102,8 @@ Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubles Full troubleshooting: -- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc) -- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) +- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/datzi/channels/imessage#troubleshooting-macos-privacy-and-security-tcc) +- /channels/bluebubbles#troubleshooting ## Signal @@ -117,7 +115,7 @@ Full troubleshooting: | DM blocked | `datzi pairing list signal` | Approve sender or adjust DM policy. | | Group replies do not trigger | Check group allowlist and mention patterns | Add sender/group or loosen gating. | -Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubleshooting) +Full troubleshooting: /channels/signal#troubleshooting ## Matrix @@ -129,4 +127,4 @@ Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubl | DMs do not process | `datzi pairing list matrix` | Approve sender or adjust DM policy. | | Encrypted rooms fail | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. | -Full troubleshooting: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting) +Full troubleshooting: /channels/matrix#troubleshooting diff --git a/datzi/channels/whatsapp.mdx b/datzi/channels/whatsapp.mdx index f46a1f8..8b933ee 100644 --- a/datzi/channels/whatsapp.mdx +++ b/datzi/channels/whatsapp.mdx @@ -18,8 +18,6 @@ tags: ] --- -# WhatsApp - # WhatsApp (Web channel) Status: production-ready via WhatsApp Web (Baileys). Gateway owns linked session(s). @@ -255,7 +253,7 @@ Behavior notes: ## Configuration reference pointers -- [Configuration reference - WhatsApp](/gateway/configuration-reference#whatsapp) +- [Configuration reference - WhatsApp](/datzi/gateway/configuration-reference#whatsapp) High-signal WhatsApp fields: @@ -267,7 +265,7 @@ High-signal WhatsApp fields: ## Related -- [Pairing](/channels/pairing) -- [Channel routing](/channels/channel-routing) -- [Multi-agent routing](/concepts/multi-agent) -- [Troubleshooting](/channels/troubleshooting) +- [Pairing](/datzi/channels/pairing) +- [Channel routing](/datzi/channels/channel-routing) +- [Multi-agent routing](/datzi/concepts/multi-agent) +- [Troubleshooting](/datzi/channels/troubleshooting) diff --git a/datzi/cli/README.md b/datzi/cli/README.md deleted file mode 100644 index b891124..0000000 --- a/datzi/cli/README.md +++ /dev/null @@ -1,38 +0,0 @@ -| ID | Title | Slug | Summary | -| --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | -| DATZI-040 | `datzi agent` | agent | Run an agent turn via the Gateway (use --local for embedded). | -| DATZI-041 | `datzi agents` | agents | Manage isolated agents (workspaces + auth + routing). | -| DATZI-042 | `datzi approvals` | approvals | Manage exec approvals for the **local host**, **gateway host**, or a **node host**. | -| DATZI-043 | `datzi browser` | browser | Manage Datzi’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks. | -| DATZI-044 | `datzi channels` | channels | Manage chat channel accounts and their runtime status on the Gateway. | -| DATZI-045 | `datzi configure` | configure | Interactive prompt to set up credentials, devices, and agent defaults. | -| DATZI-046 | `datzi cron` | cron | Manage cron jobs for the Gateway scheduler. | -| DATZI-047 | `datzi dashboard` | dashboard | Open the Control UI using your current auth. | -| DATZI-048 | `datzi directory` | directory | Directory lookups for channels that support it (contacts/peers, groups, and “me”). | -| DATZI-049 | `datzi dns` | dns | DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS. | -| DATZI-050 | `datzi docs` | docs | Search the live docs index. | -| DATZI-051 | CLI reference | index | This page describes the current CLI behavior. If commands change, update this doc. | -| DATZI-052 | `datzi doctor` | doctor | Health checks + quick fixes for the gateway and channels. | -| DATZI-053 | Gateway CLI | gateway | The Gateway is Datzi’s WebSocket server (channels, nodes, sessions, hooks). | -| DATZI-054 | `datzi health` | health | Fetch health from the running Gateway. | -| DATZI-055 | `datzi hooks` | hooks | Manage agent hooks (event-driven automations for commands like /new, /reset, and gateway startup). | -| DATZI-056 | `datzi logs` | logs | Tail Gateway file logs over RPC (works in remote mode). | -| DATZI-057 | `datzi memory` | memory | Manage semantic memory indexing and search. | -| DATZI-058 | `datzi message` | message | Single outbound command for sending messages and channel actions. | -| DATZI-059 | `datzi models` | models | Model discovery, scanning, and configuration (default model, fallbacks, auth profiles). | -| DATZI-060 | `datzi nodes` | nodes | Manage paired nodes (devices) and invoke node capabilities. | -| DATZI-061 | `datzi onboard` | onboard | Interactive onboarding wizard (local or remote Gateway setup). | -| DATZI-062 | `datzi pairing` | pairing | Approve or inspect DM pairing requests (for channels that support pairing). | -| DATZI-063 | `datzi plugins` | plugins | Manage Gateway plugins/extensions (loaded in-process). | -| DATZI-064 | `datzi reset` | reset | Reset local config/state (keeps the CLI installed). | -| DATZI-065 | Sandbox CLI | sandbox | Manage Docker-based sandbox containers for isolated agent execution. | -| DATZI-066 | `datzi security` | security | Security tools (audit + optional fixes). | -| DATZI-067 | `datzi sessions` | sessions | List stored conversation sessions. | -| DATZI-068 | `datzi setup` | setup | Initialize ~/.datzi/datzi.json and the agent workspace. | -| DATZI-069 | `datzi skills` | skills | Inspect skills (bundled + workspace + managed overrides) and see what’s eligible vs missing requirements. | -| DATZI-070 | `datzi status` | status | Diagnostics for channels + sessions. | -| DATZI-071 | `datzi system` | system | System-level helpers for the Gateway: enqueue system events, control heartbeats. | -| DATZI-072 | `datzi tui` | tui | Open the terminal UI connected to the Gateway. | -| DATZI-073 | `datzi uninstall` | uninstall | Uninstall the gateway service + local data (CLI remains). | -| DATZI-074 | `datzi update` | update | Safely update Datzi and switch between stable/beta/dev channels. | -| DATZI-075 | `datzi voicecall` | voicecall | voicecall is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled. | diff --git a/datzi/cli/agent.mdx b/datzi/cli/agent.mdx deleted file mode 100644 index 0b1de92..0000000 --- a/datzi/cli/agent.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: DATZI-040 -category: cli -slug: agent -title: `datzi agent` -summary: Run an agent turn via the Gateway (use --local for embedded). -tags: ["cli", "agent"] ---- - -# `datzi agent` - -Run an agent turn via the Gateway (use `--local` for embedded). -Use `--agent ` to target a configured agent directly. - -Related: - -- Agent send tool: [Agent send](/tools/agent-send) - -## Examples - -```bash -datzi agent --to +15555550123 --message "status update" --deliver -datzi agent --agent ops --message "Summarize logs" -datzi agent --session-id 1234 --message "Summarize inbox" --thinking medium -datzi agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports" -``` - -# agents diff --git a/datzi/cli/agents.mdx b/datzi/cli/agents.mdx deleted file mode 100644 index 1f72303..0000000 --- a/datzi/cli/agents.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -id: DATZI-041 -category: cli -slug: agents -title: `datzi agents` -summary: Manage isolated agents (workspaces + auth + routing). -tags: ["cli", "agents"] ---- - -# `datzi agents` - -Manage isolated agents (workspaces + auth + routing). - -Related: - -- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent) -- Agent workspace: [Agent workspace](/concepts/agent-workspace) - -## Examples - -```bash -datzi agents list -datzi agents add work --workspace ~/.datzi/workspace-work -datzi agents set-identity --workspace ~/.datzi/workspace --from-identity -datzi agents set-identity --agent main --avatar avatars/datzi.png -datzi agents delete work -``` - -## Identity files - -Each agent workspace can include an `IDENTITY.md` at the workspace root: - -- Example path: `~/.datzi/workspace/IDENTITY.md` -- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`) - -Avatar paths resolve relative to the workspace root. - -## Set identity - -`set-identity` writes fields into `agents.list[].identity`: - -- `name` -- `theme` -- `emoji` -- `avatar` (workspace-relative path, http(s) URL, or data URI) - -Load from `IDENTITY.md`: - -```bash -datzi agents set-identity --workspace ~/.datzi/workspace --from-identity -``` - -Override fields explicitly: - -```bash -datzi agents set-identity --agent main --name "Datzi" --emoji "🐟" --avatar avatars/datzi.png -``` - -Config sample: - -```json5 -{ - agents: { - list: [ - { - id: 'main', - identity: { - name: 'Datzi', - theme: 'goldfish pond', - emoji: '🐟', - avatar: 'avatars/datzi.png' - } - } - ] - } -} -``` - -# approvals diff --git a/datzi/cli/approvals.mdx b/datzi/cli/approvals.mdx deleted file mode 100644 index 5bc7bdb..0000000 --- a/datzi/cli/approvals.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: DATZI-042 -category: cli -slug: approvals -title: `datzi approvals` -summary: Manage exec approvals for the **local host**, **gateway host**, or a **node host**. -tags: ["cli", "approvals"] ---- - -# `datzi approvals` - -Manage exec approvals for the **local host**, **gateway host**, or a **node host**. -By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to -target a specific node. - -Related: - -- Exec approvals: [Exec approvals](/tools/exec-approvals) -- Nodes: [Nodes](/nodes) - -## Common commands - -```bash -datzi approvals get -datzi approvals get --node -datzi approvals get --gateway -``` - -## Replace approvals from a file - -```bash -datzi approvals set --file ./exec-approvals.json -datzi approvals set --node --file ./exec-approvals.json -datzi approvals set --gateway --file ./exec-approvals.json -``` - -## Allowlist helpers - -```bash -datzi approvals allowlist add "~/Projects/**/bin/rg" -datzi approvals allowlist add --agent main --node "/usr/bin/uptime" -datzi approvals allowlist add --agent "*" "/usr/bin/uname" - -datzi approvals allowlist remove "~/Projects/**/bin/rg" -``` - -## Notes - -- `--node` uses the same resolver as `datzi nodes` (id, name, ip, or id prefix). -- `--agent` defaults to `"*"`, which applies to all agents. -- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host). -- Approvals files are stored per host at `~/.datzi/exec-approvals.json`. - -# browser diff --git a/datzi/cli/browser.mdx b/datzi/cli/browser.mdx deleted file mode 100644 index f762dd1..0000000 --- a/datzi/cli/browser.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -id: DATZI-043 -category: cli -slug: browser -title: `datzi browser` -summary: Manage Datzi’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks. -tags: ["cli", "browser"] ---- - -# `datzi browser` - -Manage Datzi’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, -typing). - -Related: - -- Browser tool + API: [Browser tool](/tools/browser) -- Chrome extension relay: [Chrome extension](/tools/chrome-extension) - -## Common flags - -- `--url `: Gateway WebSocket URL (defaults to config). -- `--token `: Gateway token (if required). -- `--timeout `: request timeout (ms). -- `--browser-profile `: choose a browser profile (default from config). -- `--json`: machine-readable output (where supported). - -## Quick start (local) - -```bash -datzi browser --browser-profile chrome tabs -datzi browser --browser-profile datzi start -datzi browser --browser-profile datzi open https://example.com -datzi browser --browser-profile datzi snapshot -``` - -## Profiles - -Profiles are named browser routing configs. In practice: - -- `datzi`: launches/attaches to a dedicated Datzi-managed Chrome instance (isolated user data dir). -- `chrome`: controls your existing Chrome tab(s) via the Chrome extension relay. - -```bash -datzi browser profiles -datzi browser create-profile --name work --color "#FF5A36" -datzi browser delete-profile --name work -``` - -Use a specific profile: - -```bash -datzi browser --browser-profile work tabs -``` - -## Tabs - -```bash -datzi browser tabs -datzi browser focus -datzi browser close -``` - -## Snapshot / screenshot / actions - -Snapshot: - -```bash -datzi browser snapshot -``` - -Screenshot: - -```bash -datzi browser screenshot -``` - -Navigate/click/type (ref-based UI automation): - -```bash -datzi browser navigate https://example.com -datzi browser click -datzi browser type "hello" -``` - -## Chrome extension relay (attach via toolbar button) - -This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach). - -Install the unpacked extension to a stable path: - -```bash -datzi browser extension install -datzi browser extension path -``` - -Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder. - -Full guide: [Chrome extension](/tools/chrome-extension) - -## Remote browser control (node host proxy) - -If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has -Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server -required). - -Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if -multiple are connected. - -Security + remote -setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security) - -# channels diff --git a/datzi/cli/channels.mdx b/datzi/cli/channels.mdx deleted file mode 100644 index 903626d..0000000 --- a/datzi/cli/channels.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: DATZI-044 -category: cli -slug: channels -title: `datzi channels` -summary: Manage chat channel accounts and their runtime status on the Gateway. -tags: ["cli", "channels"] ---- - -# `datzi channels` - -Manage chat channel accounts and their runtime status on the Gateway. - -Related docs: - -- Channel guides: [Channels](/channels/index) -- Gateway configuration: [Configuration](/gateway/configuration) - -## Common commands - -```bash -datzi channels list -datzi channels status -datzi channels capabilities -datzi channels capabilities --channel discord --target channel:123 -datzi channels resolve --channel slack "#general" "@jane" -datzi channels logs --channel all -``` - -## Add / remove accounts - -```bash -datzi channels add --channel telegram --token -datzi channels remove --channel telegram --delete -``` - -Tip: `datzi channels add --help` shows per-channel flags (token, app token, signal-cli paths, etc). - -## Login / logout (interactive) - -```bash -datzi channels login --channel whatsapp -datzi channels logout --channel whatsapp -``` - -## Troubleshooting - -- Run `datzi status --deep` for a broad probe. -- Use `datzi doctor` for guided fixes. -- `datzi channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. - Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via - Claude Code CLI. - -## Capabilities probe - -Fetch provider capability hints (intents/scopes where available) plus static feature support: - -```bash -datzi channels capabilities -datzi channels capabilities --channel discord --target channel:123 -``` - -Notes: - -- `--channel` is optional; omit it to list every channel (including extensions). -- `--target` accepts `channel:` or a raw numeric channel id and only applies to Discord. -- Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot - flags + webhook; Signal daemon version; MS Teams app token + Graph roles/scopes (annotated where known). Channels - without probes report `Probe: unavailable`. - -## Resolve names to IDs - -Resolve channel/user names to IDs using the provider directory: - -```bash -datzi channels resolve --channel slack "#general" "@jane" -datzi channels resolve --channel discord "My Server/#support" "@someone" -datzi channels resolve --channel matrix "Project Room" -``` - -Notes: - -- Use `--kind user|group|auto` to force the target type. -- Resolution prefers active matches when multiple entries share the same name. - -# configure diff --git a/datzi/cli/configure.mdx b/datzi/cli/configure.mdx deleted file mode 100644 index 9af164e..0000000 --- a/datzi/cli/configure.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: DATZI-045 -category: cli -slug: configure -title: `datzi configure` -summary: Interactive prompt to set up credentials, devices, and agent defaults. -tags: ["cli", "configure"] ---- - -# `datzi configure` - -Interactive prompt to set up credentials, devices, and agent defaults. - -Note: The **Model** section now includes a multi-select for the -`agents.defaults.models` allowlist (what shows up in `/model` and the model picker). - -Tip: `datzi config` without a subcommand opens the same wizard. Use -`datzi config get|set|unset` for non-interactive edits. - -Related: - -- Gateway configuration reference: [Configuration](/gateway/configuration) -- Config CLI: [Config](/cli/config) - -Notes: - -- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if - that is all you need. -- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You - can enter names or IDs; the wizard resolves names to IDs when possible. - -## Examples - -```bash -datzi configure -datzi configure --section models --section channels -``` - -# cron diff --git a/datzi/cli/cron.mdx b/datzi/cli/cron.mdx deleted file mode 100644 index 1ec70d6..0000000 --- a/datzi/cli/cron.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: DATZI-046 -category: cli -slug: cron -title: `datzi cron` -summary: Manage cron jobs for the Gateway scheduler. -tags: ["cli", "cron"] ---- - -# `datzi cron` - -Manage cron jobs for the Gateway scheduler. - -Related: - -- Cron jobs: [Cron jobs](/automation/cron-jobs) - -Tip: run `datzi cron --help` for the full command surface. - -Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep -output internal. `--deliver` remains as a deprecated alias for `--announce`. - -Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them. - -Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return -to normal schedule after the next successful run. - -## Common edits - -Update delivery settings without changing the message: - -```bash -datzi cron edit --announce --channel telegram --to "123456789" -``` - -Disable delivery for an isolated job: - -```bash -datzi cron edit --no-deliver -``` - -Announce to a specific channel: - -```bash -datzi cron edit --announce --channel slack --to "channel:C1234567890" -``` - -# dashboard diff --git a/datzi/cli/dashboard.mdx b/datzi/cli/dashboard.mdx deleted file mode 100644 index 8a67078..0000000 --- a/datzi/cli/dashboard.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: DATZI-047 -category: cli -slug: dashboard -title: `datzi dashboard` -summary: Open the Control UI using your current auth. -tags: ["cli", "dashboard"] ---- - -# `datzi dashboard` - -Open the Control UI using your current auth. - -```bash -datzi dashboard -datzi dashboard --no-open -``` - -# directory diff --git a/datzi/cli/directory.mdx b/datzi/cli/directory.mdx deleted file mode 100644 index 8bf3743..0000000 --- a/datzi/cli/directory.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -id: DATZI-048 -category: cli -slug: directory -title: `datzi directory` -summary: Directory lookups for channels that support it (contacts/peers, groups, and “me”). -tags: ["cli", "directory"] ---- - -# `datzi directory` - -Directory lookups for channels that support it (contacts/peers, groups, and “me”). - -## Common flags - -- `--channel `: channel id/alias (required when multiple channels are configured; auto when only one is - configured) -- `--account `: account id (default: channel default) -- `--json`: output JSON - -## Notes - -- `directory` is meant to help you find IDs you can paste into other commands (especially - `datzi message send --target ...`). -- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory. -- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting. - -## Using results with `message send` - -```bash -datzi directory peers list --channel slack --query "U0" -datzi message send --channel slack --target user:U012ABCDEF --message "hello" -``` - -## ID formats (by channel) - -- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group) -- Telegram: `@username` or numeric chat id; groups are numeric ids -- Slack: `user:U…` and `channel:C…` -- Discord: `user:` and `channel:` -- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server` -- Microsoft Teams (plugin): `user:` and `conversation:` -- Zalo (plugin): user id (Bot API) -- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`) - -## Self (“me”) - -```bash -datzi directory self --channel zalouser -``` - -## Peers (contacts/users) - -```bash -datzi directory peers list --channel zalouser -datzi directory peers list --channel zalouser --query "name" -datzi directory peers list --channel zalouser --limit 50 -``` - -## Groups - -```bash -datzi directory groups list --channel zalouser -datzi directory groups list --channel zalouser --query "work" -datzi directory groups members --channel zalouser --group-id -``` - -# dns diff --git a/datzi/cli/dns.mdx b/datzi/cli/dns.mdx deleted file mode 100644 index 7e20c50..0000000 --- a/datzi/cli/dns.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: DATZI-049 -category: cli -slug: dns -title: `datzi dns` -summary: DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS. -tags: ["cli", "dns"] ---- - -# `datzi dns` - -DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS. - -Related: - -- Gateway discovery: [Discovery](/gateway/discovery) -- Wide-area discovery config: [Configuration](/gateway/configuration) - -## Setup - -```bash -datzi dns setup -datzi dns setup --apply -``` - -# docs diff --git a/datzi/cli/docs.mdx b/datzi/cli/docs.mdx deleted file mode 100644 index bc1fe66..0000000 --- a/datzi/cli/docs.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: DATZI-050 -category: cli -slug: docs -title: `datzi docs` -summary: Search the live docs index. -tags: ["cli", "docs"] ---- - -# `datzi docs` - -Search the live docs index. - -```bash -datzi docs browser extension -datzi docs sandbox allowHostControl -``` - -# CLI Reference diff --git a/datzi/cli/doctor.mdx b/datzi/cli/doctor.mdx deleted file mode 100644 index 482f826..0000000 --- a/datzi/cli/doctor.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -id: DATZI-052 -category: cli -slug: doctor -title: `datzi doctor` -summary: Health checks + quick fixes for the gateway and channels. -tags: ["cli", "doctor"] ---- - -# `datzi doctor` - -Health checks + quick fixes for the gateway and channels. - -Related: - -- Troubleshooting: [Troubleshooting](/gateway/troubleshooting) -- Security audit: [Security](/gateway/security) - -## Examples - -```bash -datzi doctor -datzi doctor --repair -datzi doctor --deep -``` - -Notes: - -- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. - Headless runs (cron, Telegram, no terminal) will skip prompts. -- `--fix` (alias for `--repair`) writes a backup to `~/.datzi/datzi.json.bak` and drops unknown config keys, - listing each removal. - -## macOS: `launchctl` env overrides - -If you previously ran `launchctl setenv DATZI_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config -file and can cause persistent “unauthorized” errors. - -```bash -launchctl getenv DATZI_GATEWAY_TOKEN -launchctl getenv DATZI_GATEWAY_PASSWORD - -launchctl unsetenv DATZI_GATEWAY_TOKEN -launchctl unsetenv DATZI_GATEWAY_PASSWORD -``` - -# gateway diff --git a/datzi/cli/gateway.mdx b/datzi/cli/gateway.mdx deleted file mode 100644 index c707b83..0000000 --- a/datzi/cli/gateway.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -id: DATZI-053 -category: cli -slug: gateway -title: Gateway CLI -summary: The Gateway is Datzi’s WebSocket server (channels, nodes, sessions, hooks). -tags: ['cli', 'gateway'] ---- - -# Gateway CLI - -The Gateway is Datzi’s WebSocket server (channels, nodes, sessions, hooks). - -Subcommands in this page live under `datzi gateway …`. - -Related docs: - -- [/gateway/bonjour](/gateway/bonjour) -- [/gateway/discovery](/gateway/discovery) -- [/gateway/configuration](/gateway/configuration) - -## Run the Gateway - -Run a local Gateway process: - -```bash -datzi gateway -``` - -Foreground alias: - -```bash -datzi gateway run -``` - -Notes: - -- By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.datzi/datzi.json`. Use - `--allow-unconfigured` for ad-hoc/dev runs. -- Binding beyond loopback without auth is blocked (safety guardrail). -- `SIGUSR1` triggers an in-process restart when authorized (`commands.restart` is enabled by default; set - `commands.restart: false` to block manual restart, while gateway tool/config apply/update remain allowed). -- `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap - the CLI with a TUI or raw-mode input, restore the terminal before exit. - -### Options - -- `--port `: WebSocket port (default comes from config/env; usually `18789`). -- `--bind `: listener bind mode. -- `--auth `: auth mode override. -- `--token `: token override (also sets `DATZI_GATEWAY_TOKEN` for the process). -- `--password `: password override (also sets `DATZI_GATEWAY_PASSWORD` for the process). -- `--tailscale `: expose the Gateway via Tailscale. -- `--tailscale-reset-on-exit`: reset Tailscale serve/funnel config on shutdown. -- `--allow-unconfigured`: allow gateway start without `gateway.mode=local` in config. -- `--dev`: create a dev config + workspace if missing (skips BOOTSTRAP.md). -- `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`). -- `--force`: kill any existing listener on the selected port before starting. -- `--verbose`: verbose logs. -- `--claude-cli-logs`: only show claude-cli logs in the console (and enable its stdout/stderr). -- `--ws-log `: websocket log style (default `auto`). -- `--compact`: alias for `--ws-log compact`. -- `--raw-stream`: log raw model stream events to jsonl. -- `--raw-stream-path `: raw stream jsonl path. - -## Query a running Gateway - -All query commands use WebSocket RPC. - -Output modes: - -- Default: human-readable (colored in TTY). -- `--json`: machine-readable JSON (no styling/spinner). -- `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout. - -Shared options (where supported): - -- `--url `: Gateway WebSocket URL. -- `--token `: Gateway token. -- `--password `: Gateway password. -- `--timeout `: timeout/budget (varies per command). -- `--expect-final`: wait for a “final” response (agent calls). - -Note: when you set `--url`, the CLI does not fall back to config or environment credentials. -Pass `--token` or `--password` explicitly. Missing explicit credentials is an error. - -### `gateway health` - -```bash -datzi gateway health --url ws://127.0.0.1:18789 -``` - -### `gateway status` - -`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe. - -```bash -datzi gateway status -datzi gateway status --json -``` - -Options: - -- `--url `: override the probe URL. -- `--token `: token auth for the probe. -- `--password `: password auth for the probe. -- `--timeout `: probe timeout (default `10000`). -- `--no-probe`: skip the RPC probe (service-only view). -- `--deep`: scan system-level services too. - -### `gateway probe` - -`gateway probe` is the “debug everything” command. It always probes: - -- your configured remote gateway (if set), and -- localhost (loopback) **even if remote is configured**. - -If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated -profiles/ports (e.g., a rescue bot), but most installs still run a single gateway. - -```bash -datzi gateway probe -datzi gateway probe --json -``` - -#### Remote over SSH (Mac app parity) - -The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback -only) becomes reachable at `ws://127.0.0.1:`. - -CLI equivalent: - -```bash -datzi gateway probe --ssh user@gateway-host -``` - -Options: - -- `--ssh `: `user@host` or `user@host:port` (port defaults to `22`). -- `--ssh-identity `: identity file. -- `--ssh-auto`: pick the first discovered gateway host as SSH target (LAN/WAB only). - -Config (optional, used as defaults): - -- `gateway.remote.sshTarget` -- `gateway.remote.sshIdentity` - -### `gateway call ` - -Low-level RPC helper. - -```bash -datzi gateway call status -datzi gateway call logs.tail --params '{"sinceMs": 60000}' -``` - -## Manage the Gateway service - -```bash -datzi gateway install -datzi gateway start -datzi gateway stop -datzi gateway restart -datzi gateway uninstall -``` - -Notes: - -- `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`. -- Lifecycle commands accept `--json` for scripting. - -## Discover gateways (Bonjour) - -`gateway discover` scans for Gateway beacons (`_datzi-gw._tcp`). - -- Multicast DNS-SD: `local.` -- Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: `datzi.internal.`) and set up split DNS + a DNS - server; see [/gateway/bonjour](/gateway/bonjour) - -Only gateways with Bonjour discovery enabled (default) advertise the beacon. - -Wide-Area discovery records include (TXT): - -- `role` (gateway role hint) -- `transport` (transport hint, e.g. `gateway`) -- `gatewayPort` (WebSocket port, usually `18789`) -- `sshPort` (SSH port; defaults to `22` if not present) -- `tailnetDns` (MagicDNS hostname, when available) -- `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint) -- `cliPath` (optional hint for remote installs) - -### `gateway discover` - -```bash -datzi gateway discover -``` - -Options: - -- `--timeout `: per-command timeout (browse/resolve); default `2000`. -- `--json`: machine-readable output (also disables styling/spinner). - -Examples: - -```bash -datzi gateway discover --timeout 4000 -datzi gateway discover --json | jq '.beacons[].wsUrl' -``` - -# health diff --git a/datzi/cli/health.mdx b/datzi/cli/health.mdx deleted file mode 100644 index 67c503c..0000000 --- a/datzi/cli/health.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: DATZI-054 -category: cli -slug: health -title: `datzi health` -summary: Fetch health from the running Gateway. -tags: ["cli", "health"] ---- - -# `datzi health` - -Fetch health from the running Gateway. - -```bash -datzi health -datzi health --json -datzi health --verbose -``` - -Notes: - -- `--verbose` runs live probes and prints per-account timings when multiple accounts are configured. -- Output includes per-agent session stores when multiple agents are configured. - -# hooks diff --git a/datzi/cli/hooks.mdx b/datzi/cli/hooks.mdx deleted file mode 100644 index 96deedf..0000000 --- a/datzi/cli/hooks.mdx +++ /dev/null @@ -1,315 +0,0 @@ ---- -id: DATZI-055 -category: cli -slug: hooks -title: `datzi hooks` -summary: Manage agent hooks (event-driven automations for commands like /new, /reset, and gateway startup). -tags: ["cli", "hooks"] ---- - -# `datzi hooks` - -Manage agent hooks (event-driven automations for commands like `/new`, `/reset`, and gateway startup). - -Related: - -- Hooks: [Hooks](/automation/hooks) -- Plugin hooks: [Plugins](/tools/plugin#plugin-hooks) - -## List All Hooks - -```bash -datzi hooks list -``` - -List all discovered hooks from workspace, managed, and bundled directories. - -**Options:** - -- `--eligible`: Show only eligible hooks (requirements met) -- `--json`: Output as JSON -- `-v, --verbose`: Show detailed information including missing requirements - -**Example output:** - -``` -Hooks (4/4 ready) - -Ready: - 🚀 boot-md ✓ - Run BOOT.md on gateway startup - 📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap - 📝 command-logger ✓ - Log all command events to a centralized audit file - 💾 session-memory ✓ - Save session context to memory when /new command is issued -``` - -**Example (verbose):** - -```bash -datzi hooks list --verbose -``` - -Shows missing requirements for ineligible hooks. - -**Example (JSON):** - -```bash -datzi hooks list --json -``` - -Returns structured JSON for programmatic use. - -## Get Hook Information - -```bash -datzi hooks info -``` - -Show detailed information about a specific hook. - -**Arguments:** - -- ``: Hook name (e.g., `session-memory`) - -**Options:** - -- `--json`: Output as JSON - -**Example:** - -```bash -datzi hooks info session-memory -``` - -**Output:** - -``` -💾 session-memory ✓ Ready - -Save session context to memory when /new command is issued - -Details: - Source: datzi-bundled - Path: /path/to/datzi/hooks/bundled/session-memory/HOOK.md - Handler: /path/to/datzi/hooks/bundled/session-memory/handler.ts - Events: command:new - -Requirements: - Config: ✓ workspace.dir -``` - -## Check Hooks Eligibility - -```bash -datzi hooks check -``` - -Show summary of hook eligibility status (how many are ready vs. not ready). - -**Options:** - -- `--json`: Output as JSON - -**Example output:** - -``` -Hooks Status - -Total hooks: 4 -Ready: 4 -Not ready: 0 -``` - -## Enable a Hook - -```bash -datzi hooks enable -``` - -Enable a specific hook by adding it to your config (`~/.datzi/config.json`). - -**Note:** Hooks managed by plugins show `plugin:` in `datzi hooks list` and -can’t be enabled/disabled here. Enable/disable the plugin instead. - -**Arguments:** - -- ``: Hook name (e.g., `session-memory`) - -**Example:** - -```bash -datzi hooks enable session-memory -``` - -**Output:** - -``` -✓ Enabled hook: 💾 session-memory -``` - -**What it does:** - -- Checks if hook exists and is eligible -- Updates `hooks.internal.entries..enabled = true` in your config -- Saves config to disk - -**After enabling:** - -- Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev). - -## Disable a Hook - -```bash -datzi hooks disable -``` - -Disable a specific hook by updating your config. - -**Arguments:** - -- ``: Hook name (e.g., `command-logger`) - -**Example:** - -```bash -datzi hooks disable command-logger -``` - -**Output:** - -``` -⏸ Disabled hook: 📝 command-logger -``` - -**After disabling:** - -- Restart the gateway so hooks reload - -## Install Hooks - -```bash -datzi hooks install -datzi hooks install --pin -``` - -Install a hook pack from a local folder/archive or npm. - -Npm specs are **registry-only** (package name + optional version/tag). Git/URL/file -specs are rejected. Dependency installs run with `--ignore-scripts` for safety. - -**What it does:** - -- Copies the hook pack into `~/.datzi/hooks/` -- Enables the installed hooks in `hooks.internal.entries.*` -- Records the install under `hooks.internal.installs` - -**Options:** - -- `-l, --link`: Link a local directory instead of copying (adds it to `hooks.internal.load.extraDirs`) -- `--pin`: Record npm installs as exact resolved `name@version` in `hooks.internal.installs` - -**Supported archives:** `.zip`, `.tgz`, `.tar.gz`, `.tar` - -**Examples:** - -```bash -# Local directory -datzi hooks install ./my-hook-pack - -# Local archive -datzi hooks install ./my-hook-pack.zip - -# NPM package -datzi hooks install @datzi/my-hook-pack - -# Link a local directory without copying -datzi hooks install -l ./my-hook-pack -``` - -## Update Hooks - -```bash -datzi hooks update -datzi hooks update --all -``` - -Update installed hook packs (npm installs only). - -**Options:** - -- `--all`: Update all tracked hook packs -- `--dry-run`: Show what would change without writing - -When a stored integrity hash exists and the fetched artifact hash changes, -Datzi prints a warning and asks for confirmation before proceeding. Use -global `--yes` to bypass prompts in CI/non-interactive runs. - -## Bundled Hooks - -### session-memory - -Saves session context to memory when you issue `/new`. - -**Enable:** - -```bash -datzi hooks enable session-memory -``` - -**Output:** `~/.datzi/workspace/memory/YYYY-MM-DD-slug.md` - -**See:** [session-memory documentation](/automation/hooks#session-memory) - -### bootstrap-extra-files - -Injects additional bootstrap files (for example monorepo-local `AGENTS.md` / `TOOLS.md`) during `agent:bootstrap`. - -**Enable:** - -```bash -datzi hooks enable bootstrap-extra-files -``` - -**See:** [bootstrap-extra-files documentation](/automation/hooks#bootstrap-extra-files) - -### command-logger - -Logs all command events to a centralized audit file. - -**Enable:** - -```bash -datzi hooks enable command-logger -``` - -**Output:** `~/.datzi/logs/commands.log` - -**View logs:** - -```bash -# Recent commands -tail -n 20 ~/.datzi/logs/commands.log - -# Pretty-print -cat ~/.datzi/logs/commands.log | jq . - -# Filter by action -grep '"action":"new"' ~/.datzi/logs/commands.log | jq . -``` - -**See:** [command-logger documentation](/automation/hooks#command-logger) - -### boot-md - -Runs `BOOT.md` when the gateway starts (after channels start). - -**Events**: `gateway:startup` - -**Enable**: - -```bash -datzi hooks enable boot-md -``` - -**See:** [boot-md documentation](/automation/hooks#boot-md) - -# logs diff --git a/datzi/cli/index.mdx b/datzi/cli/index.mdx deleted file mode 100644 index 73035e3..0000000 --- a/datzi/cli/index.mdx +++ /dev/null @@ -1,1031 +0,0 @@ ---- -id: DATZI-051 -category: cli -slug: index -title: CLI reference -summary: This page describes the current CLI behavior. If commands change, update this doc. -tags: ['cli', 'index'] ---- - -# CLI reference - -This page describes the current CLI behavior. If commands change, update this doc. - -## Command pages - -- [`setup`](/cli/setup) -- [`onboard`](/cli/onboard) -- [`configure`](/cli/configure) -- [`config`](/cli/config) -- [`doctor`](/cli/doctor) -- [`dashboard`](/cli/dashboard) -- [`reset`](/cli/reset) -- [`uninstall`](/cli/uninstall) -- [`update`](/cli/update) -- [`message`](/cli/message) -- [`agent`](/cli/agent) -- [`agents`](/cli/agents) -- [`acp`](/cli/acp) -- [`status`](/cli/status) -- [`health`](/cli/health) -- [`sessions`](/cli/sessions) -- [`gateway`](/cli/gateway) -- [`logs`](/cli/logs) -- [`system`](/cli/system) -- [`models`](/cli/models) -- [`memory`](/cli/memory) -- [`nodes`](/cli/nodes) -- [`devices`](/cli/devices) -- [`node`](/cli/node) -- [`approvals`](/cli/approvals) -- [`sandbox`](/cli/sandbox) -- [`tui`](/cli/tui) -- [`browser`](/cli/browser) -- [`cron`](/cli/cron) -- [`dns`](/cli/dns) -- [`docs`](/cli/docs) -- [`hooks`](/cli/hooks) -- [`webhooks`](/cli/webhooks) -- [`pairing`](/cli/pairing) -- [`plugins`](/cli/plugins) (plugin commands) -- [`channels`](/cli/channels) -- [`security`](/cli/security) -- [`skills`](/cli/skills) -- [`voicecall`](/cli/voicecall) (plugin; if installed) - -## Global flags - -- `--dev`: isolate state under `~/.datzi-dev` and shift default ports. -- `--profile `: isolate state under `~/.datzi-`. -- `--no-color`: disable ANSI colors. -- `--update`: shorthand for `datzi update` (source installs only). -- `-V`, `--version`, `-v`: print version and exit. - -## Output styling - -- ANSI colors and progress indicators only render in TTY sessions. -- OSC-8 hyperlinks render as clickable links in supported terminals; otherwise we fall back to plain URLs. -- `--json` (and `--plain` where supported) disables styling for clean output. -- `--no-color` disables ANSI styling; `NO_COLOR=1` is also respected. -- Long-running commands show a progress indicator (OSC 9;4 when supported). - -## Color palette - -Datzi uses a goldfish palette for CLI output. - -- `accent` (#FF5A2D): headings, labels, primary highlights. -- `accentBright` (#FF7A3D): command names, emphasis. -- `accentDim` (#D14A22): secondary highlight text. -- `info` (#FF8A5B): informational values. -- `success` (#2FBF71): success states. -- `warn` (#FFB020): warnings, fallbacks, attention. -- `error` (#E23D2D): errors, failures. -- `muted` (#8B7F77): de-emphasis, metadata. - -Palette source of truth: `src/terminal/palette.ts` (aka “goldfish seam”). - -## Command tree - -``` -datzi [--dev] [--profile ] - setup - onboard - configure - config - get - set - unset - doctor - security - audit - reset - uninstall - update - channels - list - status - logs - add - remove - login - logout - skills - list - info - check - plugins - list - info - install - enable - disable - doctor - memory - status - index - search - message - agent - agents - list - add - delete - acp - status - health - sessions - gateway - call - health - status - probe - discover - install - uninstall - start - stop - restart - run - logs - system - event - heartbeat last|enable|disable - presence - models - list - status - set - set-image - aliases list|add|remove - fallbacks list|add|remove|clear - image-fallbacks list|add|remove|clear - scan - auth add|setup-token|paste-token - auth order get|set|clear - sandbox - list - recreate - explain - cron - status - list - add - edit - rm - enable - disable - runs - run - nodes - devices - node - run - status - install - uninstall - start - stop - restart - approvals - get - set - allowlist add|remove - browser - status - start - stop - reset-profile - tabs - open - focus - close - profiles - create-profile - delete-profile - screenshot - snapshot - navigate - resize - click - type - press - hover - drag - select - upload - fill - dialog - wait - evaluate - console - pdf - hooks - list - info - check - enable - disable - install - update - webhooks - gmail setup|run - pairing - list - approve - docs - dns - setup - tui -``` - -Note: plugins can add additional top-level commands (for example `datzi voicecall`). - -## Security - -- `datzi security audit` — audit config + local state for common security foot-guns. -- `datzi security audit --deep` — best-effort live Gateway probe. -- `datzi security audit --fix` — tighten safe defaults and chmod state/config. - -## Plugins - -Manage extensions and their config: - -- `datzi plugins list` — discover plugins (use `--json` for machine output). -- `datzi plugins info ` — show details for a plugin. -- `datzi plugins install ` — install a plugin (or add a plugin path to `plugins.load.paths`). -- `datzi plugins enable ` / `disable ` — toggle `plugins.entries..enabled`. -- `datzi plugins doctor` — report plugin load errors. - -Most plugin changes require a gateway restart. See [/plugin](/tools/plugin). - -## Memory - -Vector search over `MEMORY.md` + `memory/*.md`: - -- `datzi memory status` — show index stats. -- `datzi memory index` — reindex memory files. -- `datzi memory search ""` — semantic search over memory. - -## Chat slash commands - -Chat messages support `/...` commands (text and native). See [/tools/slash-commands](/tools/slash-commands). - -Highlights: - -- `/status` for quick diagnostics. -- `/config` for persisted config changes. -- `/debug` for runtime-only config overrides (memory, not disk; requires `commands.debug: true`). - -## Setup + onboarding - -### `setup` - -Initialize config + workspace. - -Options: - -- `--workspace `: agent workspace path (default `~/.datzi/workspace`). -- `--wizard`: run the onboarding wizard. -- `--non-interactive`: run wizard without prompts. -- `--mode `: wizard mode. -- `--remote-url `: remote Gateway URL. -- `--remote-token `: remote Gateway token. - -Wizard auto-runs when any wizard flags are present (`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`). - -### `onboard` - -Interactive wizard to set up gateway, workspace, and skills. - -Options: - -- `--workspace ` -- `--reset` (reset config + credentials + sessions + workspace before wizard) -- `--non-interactive` -- `--mode ` -- `--flow ` (manual is an alias for advanced) -- `--auth-choice ` -- `--gateway-port ` -- `--gateway-bind ` -- `--gateway-auth ` -- `--gateway-token ` -- `--gateway-password ` -- `--remote-url ` -- `--remote-token ` -- `--tailscale ` -- `--tailscale-reset-on-exit` -- `--install-daemon` -- `--no-install-daemon` (alias: `--skip-daemon`) -- `--daemon-runtime ` -- `--skip-channels` -- `--skip-skills` -- `--skip-health` -- `--skip-ui` -- `--node-manager ` (pnpm recommended; bun not recommended for Gateway runtime) -- `--json` - -### `configure` - -Interactive configuration wizard (models, channels, skills, gateway). - -### `config` - -Non-interactive config helpers (get/set/unset). Running `datzi config` with no -subcommand launches the wizard. - -Subcommands: - -- `config get `: print a config value (dot/bracket path). -- `config set `: set a value (JSON5 or raw string). -- `config unset `: remove a value. - -### `doctor` - -Health checks + quick fixes (config + gateway + legacy services). - -Options: - -- `--no-workspace-suggestions`: disable workspace memory hints. -- `--yes`: accept defaults without prompting (headless). -- `--non-interactive`: skip prompts; apply safe migrations only. -- `--deep`: scan system services for extra gateway installs. - -## Channel helpers - -### `channels` - -Manage chat channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams). - -Subcommands: - -- `channels list`: show configured channels and auth profiles. -- `channels status`: check gateway reachability and channel health (`--probe` runs extra checks; use `datzi health`or - `datzi status --deep` for gateway health probes). -- Tip: `channels status` prints warnings with suggested fixes when it can detect common misconfigurations (then points - you to `datzi doctor`). -- `channels logs`: show recent channel logs from the gateway log file. -- `channels add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode. -- `channels remove`: disable by default; pass `--delete` to remove config entries without prompts. -- `channels login`: interactive channel login (WhatsApp Web only). -- `channels logout`: log out of a channel session (if supported). - -Common options: - -- `--channel `: `whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams` -- `--account `: channel account id (default `default`) -- `--name