Responsible for advancing "the user wants to use Dedao Brain" to a truly executable state. Don't just say "installed": connection is only successful when all three pass: CLI executable, account authorized, and API readable.
First-time installation loop
Execute in order, skipping steps that are already satisfied:
- Use
command -v getnoteto check the CLI; don't assume the CLI exists just because the Skill is installed. Standalone ClawHub/OpenClaw Skills have their CLI dependencies managed by the platform; don't look for or runscripts/install.sh。 - When the CLI is missing, check
node --versionandnpm --version, then automatically executenpm install -g @getnote/cli@latest. This is the Agent's job; don't ask the user to manually copy commands; only ask the user to confirm when the system pops up an installation authorization. - Execute
getnote version; it must be able to start normally. - Execute
getnote auth status. When not logged in, rungetnote auth login, having the user confirm only in the browser; don't ask for an API Key, Cookie, or Authorization. - Execute
getnote doctor -o json. Only whendiagnostics_completed=true、ready=trueandstatus=readycan you declare a complete connection;ready=true,status=degradedmeans core capabilities are available but warnings should still be handled.successand the oldchecksfield are only for compatibility. If not ready, first handleissues[].blocking=true, then fix according tonext_actions[]. Actions requiring confirmation must not be executed silently. - In local Agents such as Codex, Claude Code, or Cursor, execute
getnote setupto synchronize the 5 domain Skills; if the current platform already carries these domain Skills via a standalone Skill package, or the CLI explicitly indicates that no supported platform was detected, don't misreport this step's failure as an account connection failure. - First use
getnote notes --limit 1 -o jsonfor write-free acceptance. Only save a test note when the user agrees to create test content.
Daily routing
| Intent | Command |
|---|---|
| Log in | getnote auth login |
| View login status | getnote auth status |
| Log out | getnote auth logout |
| Diagnose connection | getnote doctor -o json |
| View CLI capability contract | getnote capabilities -o json |
| Synchronize domain Skills for the local AI | getnote setup |
| View AI conversation quota | getnote quota -o json |
| View version | getnote version |
| Check for upgrades | getnote update --check |
| Execute upgrade | getnote update |
When parameters are uncertain, read the corresponding command's --help; don't guess parameters from old documentation.
Each command's result and next step
| Command | Read/confirm after success | What to do after success |
|---|---|---|
getnote auth login |
Browser confirmed, credentials written locally | Then run doctor -o json; don't display credentials in chat. |
getnote auth status |
Authenticated / Not authenticated or environment variable login status |
Only start auth loginwhen not logged in; only masked values may appear in the status. |
getnote auth logout |
Logged out successfully. |
Only state that the local machine has logged out; don't claim server-side authorization has been revoked. |
getnote doctor -o json |
diagnostics_completed、local_ready、ready/status/summary、checks[]、issues[]、next_actions[]、update、integrations[] |
ready=true,status=ready only indicates complete availability;degraded requires continued handling of warnings.platforms[] only indicates that the application or command was detected; it cannot prove the Skill is installed; use integrations[].skill_status/ready to determine AI access status. |
getnote capabilities -o json |
contract_version、commands、command_aliases、command_results、guarantees |
Read only during installation, upgrade, or compatibility troubleshooting; this is the sole source of truth for command and result fields. |
getnote setup -o json |
success、targets[]、installed_cli、installed_skills、authenticated、platforms[]、next_actions[]、next |
platforms[].status=installed indicates local installation is complete;verify_in_platform indicates OpenClaw (Crayfish) or QClaw is managed by the platform, and only guide the user to complete the corresponding unique next_action. Failure to detect an AI platform does not affect the CLI and account connection. |
getnote quota -o json |
data.read/write/write_note under daily/monthly.limit/used/remaining/reset_at |
describes the remaining quota by actual bucket; do not convert or merge buckets on your own. |
getnote version |
Version text | is only used to display the version; the machine contract is still based on capabilities -o json . |
getnote update --check |
Current/available new version text | Run again when there is a new version getnote update。 |
getnote update |
CLI update, Skills sync, and doctor verification results | By default, the new CLI automatically completes the full update loop; only when all steps succeed can you say the upgrade is complete. When only upgrading the CLI, use --cli-only。 |
For all commands, the exit code is the primary judgment: a non-zero exit code means failure. Use -o json Both the API and local errors return success=false、data=null、error.code/message/reason/retryable and optional request_id; do not treat HTTP 200 or "the command ran" as success.
Doctor machine decision rules
diagnostics_completed=falseor the command exits non-zero: the diagnosis itself failed, and you must not act based on incomplete output.ready=true: CLI, account authorization, and OpenAPI connectivity are all available; ifstatus=degraded, core capabilities are available but there are still non-blocking warnings.status=partial: usually--offlineskips remote checks; readlocal_readyto judge the local environment,ready=nullindicates the remote is unknown, and you must not claim it is connected.issues[].blocking=true: handle in order of priority; keepcode、details.request_idand the error fields.next_actions[]:requires_confirmation=truefirst confirm with the user, then execute the exactcommand; after execution, rerun doctor to verify.integrations[].detected=trueonly indicates that a host was discovered; onlyskill_status=installedandready=truecan confirm that the CLI-verifiable Skills are complete.unverifiedindicates the installation status is managed by the platform, and the user should confirm within the platform; do not guess success.update.update_available=trueis a non-blocking warning; only perform the upgrade action after the user explicitly requests an upgrade.
Update loop
When the user says "help me update to get the brain," that already constitutes full update authorization; do not ask the user to choose internal components such as CLI or domain Skills:
- Execute
getnote update --check; when there is a new version or Skills need to be refreshed, executegetnote update. The command upgrades the CLI, and then the new CLI automatically runssetupanddoctor, and syncs the five domain Skills bundled with the CLI. - Independent aggregate Skills hosted by ClawHub/OpenClaw are updated by the platform;
getnote updatedoes not download or overwrite that Skill. If the host supports checking for Skill updates, continue using the host flow; otherwise, only tell the user the single necessary confirmation entry point. - Check the CLI version, the sync results of the five domain Skills, and the doctor result in the update output.
- Use the most recent note read as acceptance, then tell the user the version, diagnosis result, and any remaining actions.
Security and recovery
- Do not display or record full credentials;
auth statusonly masked values may appear. - Do not log out unless the user explicitly requests it.
- When authorization times out, is denied, or the verification code expires, restart the login flow once; do not reuse the old code.
- On failure, keep the execution steps, error cause, and
request_id; do not just reply "connection failed".