feat: per-project config scope for one init

README.md

@@ -124,15 +124,22 @@ Set up your API key and install the MCP server into your AI agents.
 one init
 ```
 
-Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro. Installs globally by default, or per-project with `-p` so your team can share configs (each person uses their own API key).
+Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro.
 
-If you've already set up, `one init` shows your current status and lets you update your key, install to more agents, or reconfigure.
+**Global vs. project scope.** `one init` is interactive and asks where the setup should live:
+
+- **Global** (`~/.one/config.json`) — applies to every folder. Best when you only need one workspace / API key.
+- **Project** (`~/.one/projects/<slug>/config.json`) — scoped to the current project, stored under your home directory so secrets never land in git. Use this when different projects need different API keys, connections, or access control.
+
+When you run `one` in a project, it uses the project config if one exists and falls back to the global config otherwise. Use `one config path` to see which config is active and the full resolution order.
+
+If you've already set up, `one init` shows your current status for the active scope and lets you update your key, install to more agents, or reconfigure.
 
 | Flag | What it does |
 |------|-------------|
 | `-y` | Skip confirmations |
-| `-g` | Install globally (default) |
-| `-p` | Install for current project only |
+| `-g` | Non-interactive: write the One config globally (`~/.one/config.json`) |
+| `-p` | Non-interactive: write the One config for this project (`~/.one/projects/<slug>/config.json`) |
 
 ### `one add <platform>`
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

skills/one/SKILL.md

@@ -22,6 +22,8 @@ description: |
 
 You have access to the One CLI which lets you interact with 250+ third-party platforms through their APIs. Always include the `--agent` flag right after `one` for structured JSON output.
 
+If the user wants a separate API key / connections for a specific project (vs. their default), walk them through running `one init` from that project folder and picking the "project" scope — see `references/scoping.md`.
+
 ## Core Workflow: search -> knowledge -> execute
 
 Always follow this sequence when the user wants to do something on a connected platform:

skills/one/references/scoping.md

@@ -0,0 +1,35 @@
+# Project vs. global config
+
+The One CLI can be configured at two scopes:
+
+- **Global** — `~/.one/config.json`. Applies everywhere the user runs `one`.
+- **Project** — `~/.one/projects/<slug>/config.json`, where `<slug>` is the project root path with slashes replaced by dashes (e.g. `/Users/jane/acme` → `-Users-jane-acme`). Only applies when running `one` from inside that project folder.
+
+**Resolution order:** env vars → `.onerc` in cwd → project config → global config. Project config wins when present; otherwise the CLI falls back to the global config.
+
+## When to suggest project scope
+
+Suggest project scope when the user wants any of the following for a specific folder only, without changing their default setup:
+
+- A different One API key (e.g. sandbox workspace for a client project)
+- A different set of connections / connection keys
+- Different access control (permissions, scoped connections, knowledge-only mode)
+
+## How to set it up
+
+Do **not** hand-edit `.onerc` or config files. Walk the user through the interactive init:
+
+```bash
+cd /path/to/the/project
+one init
+```
+
+When `init` asks "Where should this setup live?", pick **"This project only"**. Init will write the config to `~/.one/projects/<slug>/config.json` and everything else (skill install, MCP) stays untouched.
+
+To see which config is currently active and the full fallback chain:
+
+```bash
+one --agent config path
+```
+
+To switch an existing project back to using the global config, delete its project config file — the CLI will automatically fall back to global on the next run.