From e084845527599e6f4e3c16a7831a7853d7c12474 Mon Sep 17 00:00:00 2001
From: Yos Riady <yos@formo.so>
Date: Wed, 29 Jul 2026 22:12:40 +0700
Subject: [PATCH] Document canonical chart settings

---
 README.md              | 6 +++++-
 SKILLS.md              | 3 ++-
 src/commands/charts.ts | 6 ++++--
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index a445751..d326e40 100644
--- a/README.md
+++ b/README.md
@@ -308,10 +308,14 @@ formo charts create --board-id brd_123 --title "Daily Active Users" \
   --x-axis date --y-axis users
 
 formo charts create --board-id brd_123 --body '{"title":"Recent Events","chart_type":"table","query":"SELECT * FROM events LIMIT 10"}'
+
+formo charts create --board-id brd_123 --title "Post-connect paths" \
+  --chart-type user_paths \
+  --settings '{"anchors":[{"type":"event","event":"connect"}],"maxSteps":5,"nodesPerStep":3}'
 ```
 
 ### `charts update <chartId> --board-id <boardId> [options]`
-Update a chart. Accepts the same options as `create`: a raw `--body '<json>'` and/or typed flags (`--title`, `--chart-type`, `--query`, `--description`, `--x-axis`, `--y-axis`, `--group-by`, `--steps`, `--settings`). Typed flags override matching `--body` keys.
+Update a chart. Accepts the same options as `create`: a raw `--body '<json>'` and/or typed flags (`--title`, `--chart-type`, `--query`, `--description`, `--x-axis`, `--y-axis`, `--group-by`, `--steps`, `--settings`). `--steps` is for funnel steps. User Paths use `--settings` with `anchors` and optional `maxSteps` / `nodesPerStep`; retention settings require an `entryFilter` key. Typed flags override matching `--body` keys.
 
 ```bash
 formo charts update chart_abc123 --board-id brd_123 --title "Renamed chart"
diff --git a/SKILLS.md b/SKILLS.md
index 85acf52..72cc960 100644
--- a/SKILLS.md
+++ b/SKILLS.md
@@ -424,7 +424,8 @@ formo charts create --board-id <boardId> [--body '<json>' | typed chart options]
 | `--chart-type` | `table`, `number`, `funnel`, `bar`, `line`, `area`, `pie`, `stacked`, `user_paths`, `retention` |
 | `--query` | SQL query for SQL-backed charts |
 | `--x-axis` / `--y-axis` / `--group-by` | Chart encodings |
-| `--steps` / `--settings` | JSON for funnel/user-path/retention chart settings |
+| `--steps` | JSON array of funnel steps |
+| `--settings` | JSON settings object. User Paths require `anchors` and accept `maxSteps` / `nodesPerStep`; retention requires an `entryFilter` key |
 
 > Requires `boards:write` scope.
 
diff --git a/src/commands/charts.ts b/src/commands/charts.ts
index 14b62d6..6385f7e 100644
--- a/src/commands/charts.ts
+++ b/src/commands/charts.ts
@@ -120,11 +120,13 @@ const chartBodyOptions = z.object({
   steps: z
     .string()
     .optional()
-    .describe('JSON array of funnel/user-path step objects'),
+    .describe('JSON array of funnel step objects'),
   settings: z
     .string()
     .optional()
-    .describe('JSON object of type-specific chart settings'),
+    .describe(
+      'JSON object of type-specific chart settings (for example, user_paths anchors/maxSteps/nodesPerStep or retention entryFilter/retentionFilter)',
+    ),
 })
 
 // ── List charts for a board ──