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.
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.
Manoj Bajaj