Align public docs with Principal/Vault/Identity terminology, current daemon API paths, and the CLI/proxy/export integration surface instead of the removed AuthService library API.
Co-authored-by: Cursor <cursoragent@cursor.com>
Unifies first-run setup into a single idempotent command that registers
identity, completes claim, and imports API keys from env. Persists
--base-url in client config for remote daemon connections.
Closes#434
Co-authored-by: Cursor <cursoragent@cursor.com>
Remove references to five pages that do not exist:
reference/provider-schema, reference/file-layout,
concepts/profiles-vs-connections, security/hosted-deployment,
guides/profiles.
Strategy: strip the links/sentences from the 59 source files rather than
creating stub pages. Card blocks pointing to missing pages are removed;
inline sentence references are removed or reworded so the surrounding
prose stays coherent.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Delete the server-rendered dashboard pages, remove the static asset mount, and route the Next dashboard provider login form through the browser-session auth path.
The skill rewrite (PR #284) and README update standardized on
"authsome <command>" (assumes "uv tool install authsome") and on
agent-driven login flows. The docs site still spoke "uvx authsome"
everywhere and didn't surface the auth-error decision tree the
skill teaches. This brings the docs in line.
Four kinds of change in one PR.
1. CLI prefix sweep ("uvx authsome" to "authsome").
Mechanical find/replace across docs/site/ excluding installation.mdx.
812 occurrences updated. installation.mdx keeps the literal "uvx"
references because they explain the one-off run path.
2. installation.mdx rewrite.
- "uv (recommended)" tab leads, with "uv tool install authsome".
- pip second.
- uvx demoted to "one-off, no install" with @latest pattern shown.
- From source unchanged.
- A Note at the top declares: every command in the docs is the
installed form; uvx users prefix with "uvx authsome@latest".
- All subsequent code blocks updated to bare "authsome".
3. New troubleshooting/auth-errors.mdx page.
Captures the decision tree the skill teaches: 401 -> revoke +
re-login; 403 -> "authsome login --scopes" (not re-registering);
wrong client creds -> "authsome remove" then re-login. Registered
in docs.json under Troubleshooting.
4. quickstart.mdx pivoted to two paths + help reflex.
Path 1: agent-driven. Install the skill, ask the agent to do a
task that needs an external service. The agent runs login itself.
Path 2: CLI-driven. The existing manual walkthrough, preserved.
Adds a Tip about reading "authsome --help" and "authsome <cmd>
--help" before guessing flags.
5. Agent-mode note on the four skill-based integration pages.
claude-code, codex, cursor, opencode each get a one-paragraph Note
clarifying that the agent runs login, opens the browser on the
user's machine for OAuth, and that users should not paste keys
into prompts or pre-run login commands. The four SDK-style
integration pages (langchain, llamaindex, openai-agents-sdk,
anthropic-sdk) are unchanged because their pattern is
developer-driven, not agent-driven.
Verified clean: no "uvx authsome" outside installation.mdx,
docs.json valid, no em-dashes introduced.
Two classes of bugs corrected, both verified against main at 69a0cb9.
Skill (skills/authsome/references/adding-provider.md):
- OAuth redirect URL was http://localhost:7999/callback. Source truth
is http://127.0.0.1:7998/auth/callback/oauth (server/urls.py:8-9
and the matching user-facing doc in custom-providers.mdx). Agents
following the skill would tell users to register OAuth apps with
a redirect URI that does not match what authsome actually serves,
causing every PKCE login to fail.
- Step numbering had two "3." entries and no "4."; renumbered.
- Provider registration link pointed at the stale
raw.githubusercontent.com/manojbajaj95/authsome fork; repointed
to agentrhq.
Stale repo owner in actively-rendered surfaces:
- CONTRIBUTING.md: git clone URL.
- docs/site/README.md: link to the repo.
- docs/site/reference/bundled-providers.mdx: "open a pull request
against" link in the upstream contribution section.
- docs/site/concepts/credential-storage.mdx: replaced
"manojbajaj95" example label with "octocat" so the sample
connection record reads as a generic GitHub username.
- src/authsome/ui/templates/_layout.html: dashboard sidebar
"Support" link and topbar "GitHub" button.
- src/authsome/ui/templates/overview.html: dashboard "Contact Us"
button on the overview page.
Out of scope:
- pyproject.toml author attribution stays as Manoj Bajaj; that is
the actual maintainer's name, not a stale fork reference.
- CHANGELOG.md has ~100 manojbajaj95 commit URLs but release-please
regenerates it; manual edits would be overwritten on next release.
Make the daemon identity registry authoritative for protected PoP requests and remove implicit default-profile identity behavior.
Store daemon-owned state under server/ while keeping CLI signing identity files under identities/.
BREAKING CHANGE: Existing implicit default-profile installs must run authsome init again; profile:default credentials are not migrated.
Entire-Checkpoint: 557455816515
Across the docs the recommended pattern is now wrapping the agent with
`uvx authsome run --`. The Python library remains supported but is
positioned as the embedding case for orchestrators that need explicit
control.
Concrete changes:
- Every provider CodeGroup (45 pages) reordered to Proxy →
Environment → Python library, with a one-line lead-in.
- Generator updated so future regenerations preserve the order.
- Agent integration pages reframed: "Pattern 1 / Pattern 2" headings
replaced with "Run under the proxy" + "Embedding the library".
- index.mdx for agent frameworks no longer presents two equal patterns.
- reference/python-library.mdx adds a top callout pointing readers at
the CLI + proxy as the supported surface.
- concepts/architecture.mdx re-frames Sidecar as the supported mode
and Library as an embedding option that shares the same layers.
Tier 1 (critical — users were misconfiguring):
- Port + callback URL fixed everywhere. All `127.0.0.1:7999/callback`
references replaced with `127.0.0.1:7998/auth/callback/oauth`, the
value actually used by `src/authsome/server/urls.py`.
- Python API rewrite. Removed every reference to the non-existent
`AuthsomeContext` and `ctx.auth.*` API. Library code samples now use
`create_auth_service()` from `authsome.server.dependencies`, returning
the real `AuthService`. Exception names corrected (the public exports
in `authsome/__init__.py` all use the `*Error` suffix).
`reference/python-library.mdx` rewritten end-to-end against the real
surface; provider CodeGroup blocks regenerated with the corrected
pattern.
- Dashboard URLs corrected. `/overview`, `/connections`, `/app/...`
replaced with the real `/ui/`, `/ui/connections`, `/ui/apps/...`
(matches the `/ui` prefix in `server/routes/ui.py`).
- `profiles-vs-connections.mdx` no longer claims a separate audit log
per profile. The file at `~/.authsome/audit.log` is shared and tagged
with the profile name.
Tier 2 (significant):
- `reference/cli.mdx` expanded with `scan`, `connection set-default`,
`ui`, and the `daemon` subcommand group (`serve`, `start`, `stop`,
`restart`, `status`, `logs`). Replaced the bogus `okta` example with
GitHub Enterprise.
- `reference/audit-log.mdx` event table corrected: the documented
`refresh` event with an `outcome` field doesn't exist; the real event
is `refresh_failed` with `error` and `fallback_available`. Added the
`scan` event.
- OAuth index: broken `/integrations/oauth/klaviyo` link fixed to
`klaviyo-oauth`. Linear row corrected to `pkce` with the real regex
host. Notion DCR host fixed to `mcp.notion.com`.
- Linear page no longer claims DCR support (the JSON has
`supports_dcr: false` and `flow: pkce`).
- Provider count drift fixed in `index.mdx`, `provider-registry.mdx`,
and `bundled-providers.mdx` (which was also missing the `notion_dcr`
row).
Tier 2.7 (integration page corrections):
- `claude-code.mdx`: replaced fabricated `/anthropic-skills:authsome`
namespace and `npx skills add` command with the real installation
procedure for the bundled `skills/authsome/SKILL.md`.
- `cursor.mdx`: link to cursor.com (was cursor.sh); rewrote the
terminal-tool advice against Cursor's real MCP config in
`~/.cursor/mcp.json`.
- `cowork.mdx`: removed unverified `github.com/cowork-ai` link.
- `nanoclaw.mdx`: framed the runners more honestly; code example no
longer assumes a specific `Agent` import.
- `anthropic-sdk.mdx`: model ID `claude-sonnet-4-6` → `claude-sonnet-4-5`.
Tier 3 (API-key dashboard URLs):
- 18 stale or wrong dashboard URLs reviewed. Five providers without a
canonical key-management page (clearbit, g2, mailchimp, mention-me,
wistia) now show a `docs` link plus a one-line note explaining why.
The rest point at verified URLs as of May 2026. Changes flow through
the generator's `APIKEY_NOTES` map and the regeneration of all 43
provider pages.
Tier 4 (filler / repetition):
- CA-install instructions consolidated to canonical location in
`troubleshooting/proxy-networking.mdx`; `installation.mdx` and
`run-agents-with-proxy.mdx` link instead of duplicating.
- "Override bundled provider" deduplicated (canonical in
`custom-providers.mdx`; removed from `provider-registry.mdx`).
- "Known v1 limitations" canonical in `daemon-trust-boundary.mdx`;
trimmed from `threat-model.mdx`.
- `quickstart.mdx` H2 duplicate dropped; export-sourcing instruction
corrected to use `eval`.
- `troubleshooting/doctor.mdx` removed "Inspect specific state" block
that duplicated `cli.mdx`.
- `concepts/the-daemon.mdx` "When the daemon is reused" subsection
promoted into the lifecycle body.
- `run-agents-with-proxy.mdx` "Limitations" H2 absorbed into one line.
- Postiz cross-linked with `headless-device-code.mdx` and vice versa.
- New "Uninstall" section in `installation.mdx`.
CodeGroup across all 45 provider pages: the "Use the token / key" section
now collapses Library / Proxy / Environment into a single tabbed widget
instead of three sequential subsections. Higher information density, one
copy-paste interaction per page.
Expandable on the daemon-api /ready response: nested checks fields render
as a typed, collapsible block instead of inline prose.
The proxy-injection.mdx snippet is no longer referenced anywhere; its
content is folded into the CodeGroup trailer prose with the env-var and
host inlined per page. Removed.
Manoj Bajaj