Skip to content

docs: sync README, skill, guide and help text with the CLI (v2.15.2) - #242

Merged
paulkr merged 1 commit into
mainfrom
docs/sync-docs-v2.15.1
Nov 19, 2026
Merged

paulkr merged 1 commit into
mainfrom
docs/sync-docs-v2.15.1

Conversation

@paulkr

@paulkr paulkr commented Nov 19, 2026

Copy link
Copy Markdown
Member

Why

The docs had drifted from the CLI. Several examples were broken outright: an agent following them would be refused (relay activate without --confirm-write), fail validation (the while flow example), or lose data (the skill told agents to "patch" a profile with sync init, which replaces it without --config).

What changed

Text only. No behaviour changes: every src/ edit is a help string, a command description or a printed hint.

  • README: Node requirement is 22.23.4+, 24.22.1+ or 26.12.1+. one init no longer installs an MCP server. New sections for one whoami, --agent mode, one onboard, flow scaffold, config path / config reset. Memory and sync corrections below.
  • Skill (skills/one/SKILL.md): the --confirm-write rule across actions, flows and relay; connection list caps at 20 in agent mode; gmail/gmailThreads (was gmail/threads); Connect needs @withone/connect 0.20.0+.
  • references/flows.md: a while example that passes the validator ($['steps'].<id> self-reference), what --mock and --dry-run really do (--mock runs file writes for real), no Ctrl+C pause, how fallback behaves, which flags resume needs again.
  • references/relay.md: 100+ source platforms (was 5), --confirm-write, don't pass --webhook-secret with --create-webhook.
  • references/scoping.md: an agent can set up a project config itself with one --agent init --auth browser --project; access settings don't follow the usual resolution order.
  • one guide content: the same corrections for flows, memory, sync and relay, plus the real topic list.
  • --help text: mem search --deep removed; the access-count reset marked as a no-op; sync delete / sync remove say they only touch the SQLite mirror; sync approve and relay get|update|delete added; cache clear describes what it clears.
  • Memory and sync, everywhere: semantic search needs pgvector as well as an OpenAI key (the bundled Postgres has none); sync init without --config replaces an existing profile; sync run needs --embed, because a profile's memory.embed isn't applied.
  • CLAUDE.md: the doc checklist points at src/cli.ts for help text.
  • Version 2.15.1 → 2.15.2, so installed skill files refresh. Publishing still waits for a tag.

Not in this PR

The audit turned up code bugs where the docs promised behaviour the code doesn't have. These docs now describe what the code does; the code is unchanged. Some of them:

  • sync run ignores a profile's memory.embed unless --embed is passed.
  • mem search --deep and --no-track do nothing.
  • flow execute --mock runs file-write steps for real.
  • Ctrl+C doesn't pause a flow run, and fallback never runs the fallback step.
  • sync init without --config silently overwrites an existing profile.
  • one --agent logout deletes both the project and global config without confirming.

The companion website PR updates the CLI, getting-started and Relay pages in withoneai/landing.

Testing

  • npm run typecheck passes.
  • Full suite: 851 pass, 22 fail, the same 22 as on main (better-sqlite3 built for a different Node on this machine).
  • The flow examples in one guide flows pass flow validate.
  • Relay claims were checked against one relay platforms and the CLI code. Server-side relay behaviour (template rendering, filter matching, a wrong webhook secret) isn't in this repo and wasn't verified.

🤖 Generated with Claude Code

Bring every doc surface in line with what the CLI does today:
README, skills/one (SKILL.md, flows, relay, scoping references),
`one guide` content, and --help / command descriptions. Text only;
no behaviour changes.

- one init no longer installs an MCP server
- Node requirement is 22.23.4+, 24.22.1+ or 26.12.1+
- relay: 100+ source platforms, --confirm-write on writing actions
- sync init without --config replaces a profile; sync run needs --embed
- semantic memory search needs pgvector as well as an OpenAI key
- flows: valid while example, real --mock / --dry-run behaviour,
  no Ctrl+C pause, fallback, resume flags

Version bumped to 2.15.2 so installed skill files refresh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paulkr
paulkr merged commit 707d603 into main Nov 19, 2026
8 checks passed
@paulkr
paulkr deleted the docs/sync-docs-v2.15.1 branch November 19, 2026 23:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant