Skip to content

fix(docs): align README, plugin, and docs with source-of-truth#272

Open
zriyansh wants to merge 1 commit into
agentrhq:mainfrom
zriyansh:fix/docs-source-of-truth
Open

fix(docs): align README, plugin, and docs with source-of-truth#272
zriyansh wants to merge 1 commit into
agentrhq:mainfrom
zriyansh:fix/docs-source-of-truth

Conversation

@zriyansh
Copy link
Copy Markdown
Contributor

Summary

Aligns documentation with what the source actually does. All claims verified against agentrhq/authsome main at 3929b86 before editing.

Verified findings that drove the edits

Provider count. src/authsome/auth/bundled_providers/ has 45 JSONs: 14 OAuth2 + 31 API key. Notion ships two entries (notion + notion_dcr); Klaviyo ships two (klaviyo + klaviyo-oauth). The README and the plugin manifest said "44 / 13 OAuth"; corrected.

Master key path. paths.py:get_server_home() → .authsome/server. vault/crypto.py docstring: "master key stored in ~/.authsome/server/master.key". Three doc pages used the top-level path; corrected.

Architecture layer status. src/authsome/ has identity/ (Ed25519 keys, did:key, PoP JWT) and audit/ modules. The architecture page's Note saying "the alpha focuses on Vault and Auth" was straightforwardly wrong. Replaced with a status table reflecting reality. Only policy/ is genuinely planned.

Hosted daemon cross-reference. AUTHSOME_DAEMON_URL and AUTHSOME_SERVER_BASE_URL ship per the 0.2.4 changelog, but the threat model classifies hosted daemons as "Caveat (VPN only)" for private and "No" for public. Cross-reference added so adopters see the constraint at the feature announcement.

Files

  • README.md44 → 45, 13 OAuth → 14 OAuth, run python → run -- python, authsome.agentr.dev → authsome.ai (consistent with fix(docs): repoint canonical to authsome.ai and drop dead links #271).
  • .claude-plugin/marketplace.json — same provider-count correction.
  • docs/site/security/threat-model.mdx — data-at-rest table and offline-disk paragraph.
  • docs/site/security/encryption.mdxlocal_key backend description.
  • docs/site/troubleshooting/doctor.mdx — both FAIL accordions and the chmod remediation. Also routes users to authsome init instead of relying on side-effect-on-first-CLI-run.
  • docs/site/concepts/credential-storage.mdxlocal_key backend description.
  • docs/site/concepts/architecture.mdx — per-layer status table replaces the stale Note. Also updates the Vault paragraph to reference ~/.authsome/server/kv_store/.
  • docs/site/changelog.mdx — hosted daemon cross-reference.

Out of scope (tracked for follow-up PRs)

  • Profile trees still show old layout. credential-storage.mdx and profiles-vs-connections.mdx display profiles/<name>/store.db as a top-level folder, which conflicts with the canonical server/kv_store/ layout in file-layout.mdx. The whole "profiles as folder" vs "profiles as key prefix" framing needs a dedicated rewrite.
  • mitmproxy CA install procedure. 10 pages mention the CA; none provide install commands for macOS, Linux, or Windows. The doctor doesn't check for it either.
  • Anthropic bundling. Currently a custom-provider register flow. Other major LLM keys (OpenAI) ship bundled.
  • Marketing site sitemap lives in authsome-web/, separate repo.

Audit claims that turned out to be wrong

  • --force is documented in the CLI reference under login (line 74) and register (line 228/231). No fix needed.
  • whoami side effect is universal, not specific. ANY first CLI command triggers home-dir init; authsome init already exists as the explicit form.

Test plan

  • After merge + Mintlify rebuild, verify the corrected provider count appears on /docs/reference/bundled-providers.
  • Spot-check the architecture page renders the status table cleanly.
  • Confirm the doctor remediation now points at the correct path: chmod 0600 ~/.authsome/server/master.key.

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
agentrhq#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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant