agentrhq · ankitranjan7 · May 22, 2026 · May 22, 2026 · May 22, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -54,6 +54,9 @@ Use Google-style docstrings for all public interfaces. Inline comments should ex
 **Update docs alongside code.**
 If you change behavior, update the relevant docstring, `README.md`, or this file in the same commit. Documentation debt accumulates faster than technical debt and is harder to pay down later.
 
+**Keep the top-level CLI agent-first.**
+The default `authsome --help` surface should stay focused on the core agent workflow (`init`, `login`, `run`, discovery, and connection management). Operator-oriented, debugging, or browser-heavy commands should live under an advanced subgroup or an equally explicit opt-in surface rather than crowding the top level.
+
 ---
 
 ## AI-assisted development

diff --git a/docs/internal/authsome-design.md b/docs/internal/authsome-design.md
@@ -329,7 +329,7 @@ authsome/
 # no explicit init required
 authsome login <provider>  # OAuth acquisition (PKCE / Device Code / DCR+PKCE / API Key)
 authsome run -- <command>  # start sidecar + agent, wire HTTP_PROXY automatically
-authsome doctor            # vault/provider/profile health checks
+authsome advanced doctor            # vault/provider/profile health checks
 authsome whoami            # show local authsome context
 authsome status            # planned: sidecar state, registered identities, vault health
 authsome audit             # planned: tail the audit log

diff --git a/docs/internal/cli-design-review.md b/docs/internal/cli-design-review.md
@@ -75,7 +75,7 @@ Docs say default: `~/.authsome/logs/authsome.log`.
 
 ### 1e. `profile` command exists but is not documented
 
-`authsome profile` with subcommands `create` and `use` appears in the CLI but is absent from `docs/site/reference/cli.mdx`.
+`authsome advanced profile` with subcommands `create` and `use` appears in the CLI but is absent from `docs/site/reference/cli.mdx`.
 
 ---
 
@@ -88,7 +88,7 @@ The CLI reference documents only `env` and `json`.
 
 ### 1g. `daemon logs` subcommand — docs show `-n 100`, actual flag is different
 
-Docs say `authsome daemon logs [-n 100]`. Actual `authsome log` (client log command) uses `-n / --lines COUNT`.  
+Docs say `authsome advanced daemon logs [-n 100]`. Actual `authsome advanced log` (client log command) uses `-n / --lines COUNT`.  
 These are two different commands (`daemon logs` tails the daemon log; `log` tails the client audit log) — the distinction and both flags need clear documentation.
 
 ---
@@ -115,7 +115,7 @@ The CLI checks `val == "ok"` for every key, so `"3" != "ok"` always renders `FAI
 
 **Location:** `src/authsome/cli/main.py:698–733`
 
-The confirmation prompt checks only `yes` flag, not `force`. Running `authsome register --force` still prompts interactively; piping no input causes a generic failure (exit 1, no useful message).
+The confirmation prompt checks only `yes` flag, not `force`. Running `authsome advanced register --force` still prompts interactively; piping no input causes a generic failure (exit 1, no useful message).
 
 The `--force` flag is forwarded only to the server for the duplicate-override check. The client prompt is never bypassed.
 
@@ -138,7 +138,7 @@ The `--force` flag is forwarded only to the server for the duplicate-override ch
 
 ### 2d. `daemon stop` reports stopped but daemon immediately restarts
 
-`authsome daemon stop` outputs "Daemon stopped." and exits 0, but a subsequent `authsome daemon status` shows `running: true` within milliseconds. The guide test for `running: false` after stop cannot pass.
+`authsome advanced daemon stop` outputs "Daemon stopped." and exits 0, but a subsequent `authsome advanced daemon status` shows `running: true` within milliseconds. The guide test for `running: false` after stop cannot pass.
 
 Whether this is supervision auto-restart or a race in the status check is not confirmed, but the CLI output creates a misleading state. Either the daemon should indicate it will restart, or the stop command should wait for the process to actually stop before returning.
 
@@ -208,10 +208,10 @@ The current scheme uses codes 1–9. `sysexits.h` reserves 64–78 for applicati
 
 ### 3f. `remove` help text doesn't mention bundled providers
 
-`authsome remove --help` says "Permanently uninstall the specified custom PROVIDER definition."  
+`authsome advanced remove --help` says "Permanently uninstall the specified custom PROVIDER definition."  
 The CLI reference says `remove` also "resets to bundled" when used on a bundled provider.
 
-If the behavior differs for bundled vs. custom providers, the `--help` text should say so. Users who accidentally run `authsome remove github` should know whether they're deleting something permanently or just resetting to defaults.
+If the behavior differs for bundled vs. custom providers, the `--help` text should say so. Users who accidentally run `authsome advanced remove github` should know whether they're deleting something permanently or just resetting to defaults.
 
 ---
 

diff --git a/docs/internal/manual-testing.md b/docs/internal/manual-testing.md
@@ -31,13 +31,13 @@ uv run authsome whoami --json
 **Expected:** Same data as structured JSON. Key fields: `home_directory`, `profile`, `principal_id`, `vault_id`, `did`, `registration_status`, `daemon_url`, `encryption_backend`, `connected_providers_count`.
 
 ```bash
-uv run authsome doctor
+uv run authsome advanced doctor
 ```
 
 **Expected:** Exit code `0`; `OK` printed for `spec_version`, `identity`, `providers`, `connections`, `vault`, `integrity`. A `Warnings:` block may appear (e.g. "no active provider connections found") — that is normal on a fresh install.
 
 ```bash
-uv run authsome doctor --json
+uv run authsome advanced doctor --json
 ```
 
 **Expected:** `{"status": "ready", "checks": {"spec_version": "ok", ...}, "issues": [], "warnings": [...]}`. The `warnings` array is non-empty on a fresh install with no connections.
@@ -227,25 +227,25 @@ uv run authsome run --quiet curl -s https://api.github.com/user
 ## 10. Log
 
 ```bash
-uv run authsome log
+uv run authsome advanced log
 ```
 
 **Expected:** Human-readable table of recent audit entries with columns `Timestamp`, `Event`, `Provider`, `Status`. Shows "No audit entries found." if empty.
 
 ```bash
-uv run authsome log -n 5
+uv run authsome advanced log -n 5
 ```
 
 **Expected:** Last 5 entries only (same table format).
 
 ```bash
-uv run authsome log -n 5 --json
+uv run authsome advanced log -n 5 --json
 ```
 
 **Expected:** JSON object with `v`, `log_file` path, and `entries` array of parsed audit event objects, each with `timestamp`, `event`, `provider`, `status`.
 
 ```bash
-uv run authsome log --raw -n 10
+uv run authsome advanced log --raw -n 10
 ```
 
 **Expected:** Last 10 lines of the raw client debug log (loguru format).
@@ -277,7 +277,7 @@ cat > /tmp/test-provider.json << 'EOF'
 }
 EOF
 
-uv run authsome register /tmp/test-provider.json
+uv run authsome advanced register /tmp/test-provider.json
 ```
 
 **Expected:** Confirmation prompt → provider registered. No `api_url` means no reachability check.
@@ -296,13 +296,13 @@ uv run authsome list | grep test-custom
 
 ```bash
 # Register again to test --force (overwrites without prompting)
-uv run authsome register /tmp/test-provider.json --force
+uv run authsome advanced register /tmp/test-provider.json --force
 ```
 
 **Expected:** Registers immediately, no confirmation prompt, no error.
 
 ```bash
-uv run authsome remove test-custom
+uv run authsome advanced remove test-custom
 ```
 
 **Expected:** `Removed provider test-custom.`
@@ -335,23 +335,23 @@ uv run authsome list  # github → not_connected
 ## 14. Daemon
 
 ```bash
-uv run authsome daemon status
+uv run authsome advanced daemon status
 ```
 
 **Expected:** JSON showing `running: true`, health checks all `ok`, PID, and log file path. The `health` block includes `version`, `mode`, `encryption_backend`.
 
 ```bash
-uv run authsome daemon stop
-uv run authsome daemon status
+uv run authsome advanced daemon stop
+uv run authsome advanced daemon status
 ```
 
 **Expected:** "Daemon stopped successfully"; `running: false` after stop.
 
 > **Note:** If no PID record exists (e.g. after `rm -rf ~/.authsome`), `daemon stop` falls back to finding the process by port and kills it.
 
 ```bash
-uv run authsome daemon start
-uv run authsome daemon status
+uv run authsome advanced daemon start
+uv run authsome advanced daemon status
 ```
 
 **Expected:** "Daemon started successfully"; `running: true` after start.
@@ -424,6 +424,6 @@ uv run authsome get resend 2>&1; echo "exit: $?"
 ## Cleanup
 
 ```bash
-uv run authsome daemon stop
+uv run authsome advanced daemon stop
 rm -rf ~/.authsome
 ```
diff --git a/docs/register-provider.md b/docs/register-provider.md
@@ -154,7 +154,7 @@ During `authsome login`, the user will be prompted for the base URL, defaulting
 ## Step 5: Register the provider
 
 ```bash
-authsome register /path/to/provider.json
+authsome advanced register /path/to/provider.json
 ```
 
 Use `--yes` to skip the confirmation prompt in scripts, and `--force` to overwrite an existing provider with the same name.

diff --git a/docs/site/changelog.mdx b/docs/site/changelog.mdx
@@ -19,7 +19,7 @@ A curated summary of authsome releases. For the full per-commit log, see [CHANGE
 
   **Improved error handling.** Custom error propagation between the daemon server and CLI client.
 
-  **Non-interactive register.** New `--yes` flag on `authsome register` skips the confirmation prompt in scripts.
+  **Non-interactive register.** New `--yes` flag on `authsome advanced register` skips the confirmation prompt in scripts.
 
   **Distinct exit code for cancelled credential entry** (exit code 8) so scripts can distinguish user cancellation from authentication failure.
 </Update>

diff --git a/docs/site/concepts/credential-storage.mdx b/docs/site/concepts/credential-storage.mdx
@@ -120,7 +120,7 @@ Every provider in a profile is always in exactly one of three states. The state
 available → configured   authsome login (collects OAuth client creds)
 configured → connected   authsome login (completes auth flow)
 available → connected    authsome login (api_key providers)
-connected → available    authsome revoke or authsome remove
+connected → available    authsome revoke or authsome advanced remove
 ```
 
 If a provider is already `connected`, `authsome login <provider>` exits with an error. Pass `--force` to overwrite an existing connection.

diff --git a/docs/site/concepts/provider-registry.mdx b/docs/site/concepts/provider-registry.mdx
@@ -71,6 +71,6 @@ During `authsome login`, the user is prompted for the base URL with the JSON val
 Two ways:
 
 1. **Drop a file at `~/.authsome/providers/<name>.json`.** Authsome picks it up on the next CLI invocation.
-2. **Register through the CLI.** `authsome register ./acmecrm.json` validates the JSON, copies it into `~/.authsome/providers/`, and confirms the new provider appears in `authsome list`.
+2. **Register through the CLI.** `authsome advanced register ./acmecrm.json` validates the JSON, copies it into `~/.authsome/providers/`, and confirms the new provider appears in `authsome list`.
 
 See [Custom providers](/guides/custom-providers#override-a-bundled-provider) for the override walkthrough and full add-a-provider guide.
diff --git a/docs/site/guides/custom-providers.mdx b/docs/site/guides/custom-providers.mdx
@@ -25,7 +25,7 @@ Then write the JSON file following the schema at https://authsome.ai/docs/refere
 Output:
 
 - The full provider JSON, ready to save to `~/.authsome/providers/<name>.json`.
-- The exact `authsome register` command to install it.
+- The exact `authsome advanced register` command to install it.
 - A one-line note about anything unusual (multi-tenant `{base_url}`, non-standard header prefix, missing PKCE support, etc.).
 
 Do NOT invent endpoint URLs. If you cannot find them in the official docs, stop and tell me what you need to look up.
@@ -144,13 +144,13 @@ For the full schema with every supported field, see the [Provider schema referen
 ## Step 4: Register the provider
 
 ```bash
-authsome register ./acmecrm.json
+authsome advanced register ./acmecrm.json
 ```
 
 Authsome validates required fields, checks `auth_type`/`flow` compatibility, and copies the file into `~/.authsome/providers/`. Pass `--yes` to skip the confirmation prompt in scripts, and `--force` to overwrite an existing provider with the same name.
 
 ```bash
-authsome register ./acmecrm.json --force
+authsome advanced register ./acmecrm.json --force
 ```
 
 Confirm it's registered:

diff --git a/docs/site/guides/use-api-keys.mdx b/docs/site/guides/use-api-keys.mdx
@@ -90,7 +90,7 @@ The `--force` flag overwrites the existing connection. Pass `--connection <name>
 
 ```bash
 authsome logout openai             # remove local credential, leave provider untouched
-authsome remove openai             # delete all local state for the provider
+authsome advanced remove openai             # delete all local state for the provider
 ```
 
 For OAuth2 providers, `authsome revoke <provider>` also calls the provider's revocation endpoint. API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for them.

diff --git a/docs/site/installation.mdx b/docs/site/installation.mdx
@@ -74,7 +74,7 @@ Authsome runs on Python 3.13 or newer. It ships as a single PyPI package with no
 
 ```bash
 authsome whoami
-authsome doctor
+authsome advanced doctor
 ```
 
 `whoami` prints the home directory, registered identity handle, DID, and both the configured encryption mode and effective master-key source. `doctor` walks the home directory, verifies encryption is available, and parses every bundled provider definition. A healthy install reports `OK` for each check and exits with code `0`.
@@ -128,7 +128,7 @@ By default, authsome uses `encryption.mode = "auto"` and applies the precedence
 }
 ```
 
-Re-run `authsome doctor` to confirm the backend is reachable. The trade-offs are covered in [Encryption at rest](/security/encryption).
+Re-run `authsome advanced doctor` to confirm the backend is reachable. The trade-offs are covered in [Encryption at rest](/security/encryption).
 
 Older installs that used the implicit `default` profile must run `authsome init` again. This release does not migrate credentials under old `profile:default:*` keys.
 

diff --git a/docs/site/integrations/agents/anthropic-sdk.mdx b/docs/site/integrations/agents/anthropic-sdk.mdx
@@ -33,7 +33,7 @@ cat > /tmp/anthropic.json <<EOF
 }
 EOF
 
-authsome register /tmp/anthropic.json
+authsome advanced register /tmp/anthropic.json
 authsome login anthropic
 ```
 

diff --git a/docs/site/integrations/agents/claude-code.mdx b/docs/site/integrations/agents/claude-code.mdx
@@ -24,7 +24,7 @@ Install the authsome skill into Claude Code and log me into GitHub.
 2. Then run `authsome login github` and walk me through approving the OAuth flow.
 3. After the login completes, run `authsome list` and report which providers are now connected.
 
-If anything fails, show me the exact error and `authsome doctor` output.
+If anything fails, show me the exact error and `authsome advanced doctor` output.
 </Prompt>
 
 ## What the integration gives you
@@ -91,7 +91,7 @@ Concrete requests Claude understands. Each one maps to a specific authsome comma
 | "Switch the active GitHub connection to my work account." | `authsome login github --connection work` |
 | "Show me which providers are connected." | `authsome list` |
 | "Revoke my OpenAI key." | `authsome revoke openai` |
-| "Add a custom provider for Acme CRM." | `authsome register ./acmecrm.json` |
+| "Add a custom provider for Acme CRM." | `authsome advanced register ./acmecrm.json` |
 
 ## Why this is the safe pattern
 
@@ -165,7 +165,7 @@ For the underlying model, see [Profiles vs connections](/concepts/profiles-vs-co
 
 If a Claude-driven login hangs:
 
-- Run `authsome doctor` directly from the terminal to surface initialization errors.
+- Run `authsome advanced doctor` directly from the terminal to surface initialization errors.
 - Run `authsome --verbose login <provider>` to see the full flow including the daemon round-trips.
 - Check `~/.authsome/audit.log` for the most recent action and outcome.
 

diff --git a/docs/site/integrations/agents/codex.mdx b/docs/site/integrations/agents/codex.mdx
@@ -89,7 +89,7 @@ This pattern is cleaner than passing keys through prompts or hardcoding them int
 |---------|-----|
 | Codex starts but every API call fails with TLS errors | The mitmproxy CA isn't trusted. See [Proxy networking](/troubleshooting/proxy-networking). |
 | Codex doesn't see the env var even though `authsome run` set it | Verify with `authsome run -- env \| grep OPENAI`. |
-| Authsome login hangs | `authsome doctor` and check port 7998 availability. |
+| Authsome login hangs | `authsome advanced doctor` and check port 7998 availability. |
 
 ## What's next
 

diff --git a/docs/site/integrations/api-key/ahrefs.mdx b/docs/site/integrations/api-key/ahrefs.mdx
@@ -84,7 +84,7 @@ authsome login ahrefs --connection team
 ```bash
 authsome login ahrefs --force          # rotate
 authsome logout ahrefs                  # remove local credential
-authsome remove ahrefs                  # remove all local state for the provider
+authsome advanced remove ahrefs                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Ahrefs.

diff --git a/docs/site/integrations/api-key/apollo.mdx b/docs/site/integrations/api-key/apollo.mdx
@@ -84,7 +84,7 @@ authsome login apollo --connection team
 ```bash
 authsome login apollo --force          # rotate
 authsome logout apollo                  # remove local credential
-authsome remove apollo                  # remove all local state for the provider
+authsome advanced remove apollo                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Apollo.

diff --git a/docs/site/integrations/api-key/ashby.mdx b/docs/site/integrations/api-key/ashby.mdx
@@ -84,7 +84,7 @@ authsome login ashby --connection team
 ```bash
 authsome login ashby --force          # rotate
 authsome logout ashby                  # remove local credential
-authsome remove ashby                  # remove all local state for the provider
+authsome advanced remove ashby                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Ashby.

diff --git a/docs/site/integrations/api-key/beehiiv.mdx b/docs/site/integrations/api-key/beehiiv.mdx
@@ -84,7 +84,7 @@ authsome login beehiiv --connection team
 ```bash
 authsome login beehiiv --force          # rotate
 authsome logout beehiiv                  # remove local credential
-authsome remove beehiiv                  # remove all local state for the provider
+authsome advanced remove beehiiv                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Beehiiv.

diff --git a/docs/site/integrations/api-key/brevo.mdx b/docs/site/integrations/api-key/brevo.mdx
@@ -84,7 +84,7 @@ authsome login brevo --connection team
 ```bash
 authsome login brevo --force          # rotate
 authsome logout brevo                  # remove local credential
-authsome remove brevo                  # remove all local state for the provider
+authsome advanced remove brevo                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Brevo.

diff --git a/docs/site/integrations/api-key/buffer.mdx b/docs/site/integrations/api-key/buffer.mdx
@@ -85,7 +85,7 @@ authsome login buffer --connection team
 ```bash
 authsome login buffer --force          # rotate
 authsome logout buffer                  # remove local credential
-authsome remove buffer                  # remove all local state for the provider
+authsome advanced remove buffer                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Buffer.

diff --git a/docs/site/integrations/api-key/calendly.mdx b/docs/site/integrations/api-key/calendly.mdx
@@ -84,7 +84,7 @@ authsome login calendly --connection team
 ```bash
 authsome login calendly --force          # rotate
 authsome logout calendly                  # remove local credential
-authsome remove calendly                  # remove all local state for the provider
+authsome advanced remove calendly                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Calendly.

diff --git a/docs/site/integrations/api-key/clearbit.mdx b/docs/site/integrations/api-key/clearbit.mdx
@@ -86,7 +86,7 @@ authsome login clearbit --connection team
 ```bash
 authsome login clearbit --force          # rotate
 authsome logout clearbit                  # remove local credential
-authsome remove clearbit                  # remove all local state for the provider
+authsome advanced remove clearbit                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Clearbit.

diff --git a/docs/site/integrations/api-key/dub.mdx b/docs/site/integrations/api-key/dub.mdx
@@ -84,7 +84,7 @@ authsome login dub --connection team
 ```bash
 authsome login dub --force          # rotate
 authsome logout dub                  # remove local credential
-authsome remove dub                  # remove all local state for the provider
+authsome advanced remove dub                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for Dub.co.

diff --git a/docs/site/integrations/api-key/g2.mdx b/docs/site/integrations/api-key/g2.mdx
@@ -86,7 +86,7 @@ authsome login g2 --connection team
 ```bash
 authsome login g2 --force          # rotate
 authsome logout g2                  # remove local credential
-authsome remove g2                  # remove all local state for the provider
+authsome advanced remove g2                  # remove all local state for the provider
 ```
 
 API-key providers have no revocation endpoint, so `revoke` and `remove` are equivalent for G2.
-Original file line number
+Diff line change
@@ Expand Up / @@ -33,7 +33,7 @@ cat > /tmp/anthropic.json <<EOF @@
     }
     EOF
-    authsome register /tmp/anthropic.json
+    authsome advanced register /tmp/anthropic.json
     authsome login anthropic
     ```
@@ Expand Down @@