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.
Navbar previously rendered "Authsome" as plain text with no logo or
favicon. This adds the Authsome `#` mark + wordmark as SVG logos (light
and dark variants), a favicon, and a Discord community link. The PyPI
link gets a Python brand icon, and Discord moves into footer socials
alongside GitHub.
llms.txt drops out of the navbar — it already lives in the footer's
Docs column, and the navbar slot is more valuable for the community
link.
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.
Top nav now has four tabs:
- Documentation (Get started · Concepts · Security · Project)
- Guides (Guides · Troubleshooting)
- Reference
- Integrations
Troubleshooting is folded as a sub-group under Guides since both are
task-oriented.
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.
The snippet was deleted in 50f016c (now bf5f65c after rebase) when its
content was folded into the CodeGroup trailer. The generator continued
to emit the now-broken import line at the top of every provider page,
which Mintlify surfaced as warnings on every page load.
Regenerated 43 pages plus the Postiz override that lost its custom
"What's next" cards in the regen.
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