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>
The credential-storage and profiles-vs-connections pages described
profiles as separate SQLite files under ~/.authsome/profiles/<name>/
with per-profile flock locking. The actual implementation moved to
a single DiskStore at ~/.authsome/server/kv_store/ with profile
names used as key prefixes, and the daemon is the only writer.
The storage layout trees on both pages drop the profiles/ folder
and now reflect the canonical layout in reference/file-layout.mdx.
The 'Locking' section is replaced with a Concurrency section that
explains the daemon as single writer; the per-profile flock story
is gone. The 'at a glance' table now describes profiles as key
prefixes in a shared store. The OAuth client-credentials row moves
from per-profile to server-scoped (server:<provider>:client),
matching how the daemon actually stores them. 'Which one is active'
now says explicitly that a profile is an identity handle scoped
through the PoP token.
PR #281 is the upstream rename of "profile" to "principal"; this
PR keeps the existing terminology to land cleanly ahead of that
bigger naming change.
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.
The earlier audit surfaced contradictions between docs and code that
were verified against agentrhq/authsome main at 3929b86. This fixes
the verified gaps; the rest is tracked for follow-up PRs.
Provider count: source has 45 JSONs (14 OAuth2 + 31 API key) in
src/authsome/auth/bundled_providers/. Notion ships as two entries
(notion + notion_dcr) and Klaviyo as two (klaviyo + klaviyo-oauth).
- README.md: 44 -> 45 and 13 OAuth -> 14 OAuth.
- .claude-plugin/marketplace.json: same correction in the plugin
description.
Master key path: paths.py routes the server master key to
~/.authsome/server/master.key, confirmed by vault/crypto.py and
health.py. Three doc pages had the wrong (top-level) path.
- security/threat-model.mdx: data-at-rest table and offline-disk
paragraph.
- security/encryption.mdx: local_key backend description.
- troubleshooting/doctor.mdx: both accordion FAIL examples and the
chmod remediation. Also points users at "authsome init" instead of
the side-effect-on-first-run workaround.
- concepts/credential-storage.mdx: local_key backend description.
- concepts/architecture.mdx: vault wrapping description.
Architecture layer status: src/authsome/ ships identity/ (Ed25519
keys, did:key DIDs, PoP JWT), audit/ (structured JSON events), in
addition to vault/ and auth/. Only policy/ is still planned.
- concepts/architecture.mdx: replace the "alpha focuses on Vault and
Auth" Note with a per-layer status table reflecting reality. Also
updates the SQLite backend description to the kv_store path
(~/.authsome/server/kv_store/) consistent with the canonical
filesystem layout.
Hosted daemon cross-reference: changelog 0.2.4 ships
AUTHSOME_DAEMON_URL and AUTHSOME_SERVER_BASE_URL, but the threat
model classifies hosted daemons as "Caveat (VPN only)" for private
and "No" for public. Cross-reference added to the changelog entry so
adopters see the constraint at the point of the feature
announcement.
Domain: README links updated from authsome.agentr.dev to
authsome.ai for consistency with the docs canonical URL fixed in
#271.
Out of scope (separate follow-ups):
- Profile-as-folder trees in credential-storage.mdx and
profiles-vs-connections.mdx still show profiles/<name>/store.db,
which conflicts with the new server/kv_store/ architecture. Needs
a dedicated rewrite of those pages.
- mitmproxy CA install procedure (10 pages mention it; none have an
install command).
- Anthropic bundling.
- Marketing site sitemap on authsome-web.
Mintlify generates the sitemap from seo.metatags.canonical, and the
canonical was still pointing at authsome.agentr.dev. Every <loc> in
https://authsome.ai/docs/sitemap.xml carried the old domain even
though the docs are now hosted at authsome.ai.
Domain rename:
- docs.json canonical to https://authsome.ai/docs.
- docs.json footer "Home" link to https://authsome.ai.
- custom-providers.mdx schema URL to authsome.ai.
Security disclosure:
- Drop the security@agentr.dev email path from disclosure.mdx and
route all reports through GitHub's private security advisory flow.
The email was the only contact path that needed mailbox
maintenance; GitHub advisories give us the same private channel
without it.
Dead links (target files deleted upstream in 019bdd1 and ec06181):
- roadmap.mdx: drop both references to docs/authsome-design.md
(moved to docs/internal/, not public-facing).
- daemon-trust-boundary.mdx: replace authsome-design.md reference
with a link to the public /roadmap page.
- encryption.mdx: drop docs/specs/authsome-v1.md reference; keep
the prose describing the future portable spec.
- credential-storage.mdx: same fix as encryption.mdx, also drops
one stale manojbajaj95 owner reference incidentally.
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.
The <Frame> component constrains its child to a narrow centered column.
That works for images and mermaid (which renders as SVG and scales),
but it squeezed the architecture page's text-based call graph into a
single-character column, making it unreadable.
Replaced the wrapper with a plain caption sentence above the code block.
The mermaid Frame in index.mdx stays since mermaid SVGs handle the
constraint correctly.
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`.
Manoj Bajaj