# Connect this project to CreatorNotes

You (the agent) are setting up CreatorNotes so you can read and write the
user's notes, canvases, and transcripts. Follow these steps in order. The user
does not need to tell you how; that is what this page is for.

## First: where are you running?

Pick the one line that describes you, then do what it says.

- **You cannot run shell commands** (Claude Desktop chat, claude.ai, ChatGPT,
  any chat without a terminal). Do not try to install anything and do not send
  the user to a terminal. Tell them to connect over the remote MCP server
  instead, then stop:

  - Claude Desktop or claude.ai: Settings → Connectors → Add custom connector.
    Name: cnotes. URL: https://creatornotes.app/api/mcp. Connect, sign in, and
    pick one workspace on the consent screen.
  - ChatGPT: same URL, authentication set to OAuth. The illustrated guide is
    https://creatornotes.app/chatgpt.

  The connector reads, searches, and writes notes and canvases. The CLI below
  adds skills, file uploads, and scripted workflows, and it needs a real
  machine.

- **You have a shell, but it is a sandbox that is not the user's own machine**
  (a Claude Cowork session, a cloud agent, a container that is discarded when
  the session ends). Anything you install here disappears with the sandbox and
  the user can never use it. Do what the no-shell case says: hand the user the
  connector, then stop. If you are Claude Cowork, you are in this case.

- **You have a shell on the user's own machine** (Claude Code, Codex CLI,
  Cursor's agent, a terminal the user opened). Continue with the steps below.
  The install lands in the user's home directory and stays there.

## Steps

1. Pick the install path by checking for Node:

       node --version

   - **Node 18+ present** → use the npx form everywhere below:

         npx @creator-notes/cnotes@latest init

   - **No Node, or Node < 18** → do NOT install Node, nvm, or Homebrew — that
     is a 20-minute detour and it is never needed. Install the standalone
     binary instead (macOS/Linux, no dependencies):

         curl -fsSL https://creatornotes.app/install.sh | sh

     The installer puts `cnotes` in ~/.cnotes/bin and adds it to the PATH of
     NEW shells. In your current shell, call it by full path —
     `~/.cnotes/bin/cnotes` — wherever the steps below say `cnotes` or use
     the npx prefix. Then run:

         ~/.cnotes/bin/cnotes init

2. Your shell has no browser, so init prints a "Sign-in required" notice with a
   URL like https://creatornotes.app/auth/cli. Stop there and show the user that
   URL as a link they can click. Say something like:

   "Click this to sign in to CreatorNotes, then paste back what the page gives
   you."

   Do not try to open a browser yourself, and never invent or guess a token.

3. The user signs in and the page hands them a block to paste back into this
   chat. It carries a command and a key, in this shape:

       npx @creator-notes/cnotes@latest auth login --token-stdin
       cn_xxxxxxxxxxxx

   Run the command with the key on stdin. Never put the key on the command
   line: an argument shows up in `ps` and in shell history. A heredoc does it:

       npx @creator-notes/cnotes@latest auth login --token-stdin <<'EOF'
       cn_xxxxxxxxxxxx
       EOF

   If the user pasted a single line ending in `--token cn_...` instead, run
   it exactly as given. If init managed to open a browser itself back in
   step 1, sign-in may already be done; then skip to step 4.

4. Run init again to finish:

       npx @creator-notes/cnotes@latest init

   It auto-selects the workspace when there is only one, lists the IDs to choose
   from when there are several, and installs the Claude Code skill.

5. Confirm it worked:

       npx @creator-notes/cnotes@latest --help

   init exits non-zero until setup is complete, so a clean exit and a
   "You're all set" line mean you are done.

## What init sets up

1. Authenticates the CLI and selects a workspace. A workspace and Home canvas
   are auto-created on the first sign-in.
2. Saves credentials to ~/.cnotes/config.json (mode 0600, your user only).
3. Installs the CLI skill into ~/.claude/skills/cnotes/SKILL.md when ~/.claude/
   exists, so every Claude Code session in any directory knows how to use `cnotes`.
4. Offers to install `cnotes` globally for faster calls, and to wire up Claude
   Desktop or OpenAI Codex via MCP.

Re-running init is safe. It short-circuits when already configured but still
offers any setup steps that were skipped.

## Common commands

    cnotes notes list                          # browse notes
    cnotes notes create --notes '{"key":"A","type":"Note","markdown":"# Title\n..."}'
    cnotes canvas list                         # list canvases
    cnotes canvas add-node <canvasId> --note <noteId>
    cnotes search semantic "query"             # semantic search

Prefix any command with `npx @creator-notes/cnotes@latest` if you did not install
`cnotes` globally (or with `~/.cnotes/bin/cnotes` if you used the standalone
installer and haven't opened a new shell). The full reference lives at
~/.claude/skills/cnotes/SKILL.md after install, and at https://cnotes.dev/commands.md.

## Zero-install alternative (Claude Code only)

If you are Claude Code and the user just wants their workspace connected —
e.g. a quick demo on a machine that has nothing installed — you can skip the
CLI entirely and connect over remote MCP:

    claude mcp add --transport http cnotes https://creatornotes.app/api/mcp

Authentication happens as a browser sign-in when the connection is first used.
The hosted MCP server covers reading, searching, and writing notes and
canvases; the CLI adds skills, file uploads, and scripted workflows.

## Troubleshooting

- `cnotes auth status` shows the current authentication state.
- `cnotes workspace current` shows the active workspace.
- Re-run `cnotes init` anytime; it resumes where setup left off.
- Never install Node/Homebrew to satisfy npx — the standalone installer above
  exists precisely so you don't have to.