docs: restore docs mode and simplify integrations

Author: PipDscvr

README.md

@@ -35,6 +35,25 @@ npm run build  # Static build in build/
 
 Both `start` and `serve` are pinned to port **3013**.
 
+## Integration doc modes
+
+Integration docs now have two axes:
+
+- `Overview / Local / Cloud` page structure for each integration
+- a docs-mode switch for the self-managed `Local` pages
+
+By default, local dev renders the current source-backed install flow. To render
+the production-ready self-managed copy instead, set
+`ATOMICMEMORY_DOCS_MODE=published` before `npm start` or `npm run build`:
+
+```bash
+ATOMICMEMORY_DOCS_MODE=published npm start
+ATOMICMEMORY_DOCS_MODE=published npm run build
+```
+
+The default mode is `source`, which keeps the clone-and-build instructions
+visible for unpublished integrations.
+
 ## Refreshing the HTTP API reference
 
 The `/api-reference/http/*` pages are generated from the OpenAPI spec

docs/integrations/coding-agents/claude-code-local.md

@@ -8,10 +8,21 @@ slug: /integrations/coding-agents/claude-code/local
 
 Give Claude Code persistent, cross-session memory backed by AtomicMemory. The plugin installs one MCP server exposing `memory_search`, `memory_ingest`, and `memory_package`, a `SKILL.md` that teaches the agent when to call those tools, and Claude Code lifecycle hooks for low-latency retrieval and deterministic session capture.
 
+<PublishedOnly>
+
+:::tip[Published]
+The Claude Code plugin and `@atomicmemory/mcp-server` are published. Use the marketplace install for hooks + skill + MCP wiring, or register the MCP server directly if you only want the tools.
+:::
+
+</PublishedOnly>
+
+<SourceOnly>
+
 :::danger[Source-only]
 `@atomicmemory/mcp-server` and the Claude Code plugin are not published to npm or to the Claude plugin marketplace yet. Install from a local clone of [`atomicmemory-integrations`](https://github.com/atomicmemory/atomicmemory-integrations).
 :::
 
+</SourceOnly>
 
 ## What you get
 
@@ -23,6 +34,52 @@ Give Claude Code persistent, cross-session memory backed by AtomicMemory. The pl
 
 ## Install
 
+<PublishedOnly>
+
+Install `jq` and `curl` for the shell hooks, then export config before launching Claude Code:
+
+```bash
+export ATOMICMEMORY_PROVIDER="atomicmemory"
+export ATOMICMEMORY_CAPTURE_LEVEL="balanced" # minimal|balanced|full
+
+# Optional:
+export ATOMICMEMORY_SCOPE_AGENT="claude-code"
+export ATOMICMEMORY_SCOPE_NAMESPACE="<repo-or-project>"
+export ATOMICMEMORY_SCOPE_THREAD="<thread-id>"
+```
+
+Claude Code resolves the AtomicMemory service, credentials, and base user identity automatically. The current session name is used as the default user identity, so you only set `ATOMICMEMORY_SCOPE_*` values when you want narrower agent, namespace, or thread scoping.
+
+Install the full plugin from the marketplace:
+
+```bash
+claude plugin install atomicmemory/claude-code
+claude plugin config atomicmemory/claude-code \
+  --set provider=$ATOMICMEMORY_PROVIDER
+```
+
+If you only want the MCP tools, register the published MCP server directly:
+
+```json
+{
+  "mcpServers": {
+    "atomicmemory": {
+      "command": "npx",
+      "args": ["-y", "@atomicmemory/mcp-server"],
+      "env": {
+        "ATOMICMEMORY_PROVIDER": "atomicmemory",
+        "ATOMICMEMORY_SCOPE_AGENT": "claude-code",
+        "ATOMICMEMORY_SCOPE_NAMESPACE": "repo-or-project"
+      }
+    }
+  }
+}
+```
+
+</PublishedOnly>
+
+<SourceOnly>
+
 Clone `atomicmemory-sdk` and `atomicmemory-integrations` side-by-side, then build each in order:
 
 ```bash
@@ -42,10 +99,7 @@ Install `jq` and `curl` for the shell hooks, then export config before launching
 
 ```bash
 export ATOMICMEMORY_MCP_SERVER_BIN="$HOME/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js"
-export ATOMICMEMORY_API_URL="https://memory.yourco.com"
-export ATOMICMEMORY_API_KEY="am_live_..."
 export ATOMICMEMORY_PROVIDER="atomicmemory"
-export ATOMICMEMORY_SCOPE_USER="$USER"
 export ATOMICMEMORY_CAPTURE_LEVEL="balanced" # minimal|balanced|full
 
 # Optional:
@@ -54,16 +108,33 @@ export ATOMICMEMORY_SCOPE_NAMESPACE="<repo-or-project>"
 export ATOMICMEMORY_SCOPE_THREAD="<thread-id>"
 ```
 
+Even in the source-backed flow, Claude Code derives the AtomicMemory service, credentials, and base user identity automatically. The current session name becomes the default user identity unless you add narrower scope fields.
+
 Register and install from the local repo:
 
 ```bash
 claude plugin marketplace add ./
 claude plugin install claude-code@atomicmemory
 ```
 
+</SourceOnly>
 
 ## Update and Version
 
+<PublishedOnly>
+
+After publishing hook, skill, manifest, or marketplace changes, ask users to refresh the installed plugin and fully restart Claude Code:
+
+```bash
+claude plugin update atomicmemory/claude-code
+```
+
+Existing sessions can keep old hook registrations in memory even when the installed cache on disk is fresh.
+
+</PublishedOnly>
+
+<SourceOnly>
+
 Claude Code plugin updates are version-gated. After changing hooks, skills, `hooks.json`, plugin manifests, or marketplace metadata, bump plugin versions from `atomicmemory-integrations` before `claude plugin update claude-code@atomicmemory` will refresh the installed cache.
 
 ```bash
@@ -88,20 +159,33 @@ claude plugin install claude-code@atomicmemory
 
 Fully restart Claude Code after updating. Existing sessions can keep old hook registrations in memory even when the installed cache on disk is fresh.
 
+</SourceOnly>
 
 ## Configuration
 
+<PublishedOnly>
+
+Required:
+
+| Env var | Used by | Purpose |
+|---|---|---|
+| `ATOMICMEMORY_PROVIDER` | MCP + hooks | Provider name; Claude lifecycle hooks require `atomicmemory` |
+| `ATOMICMEMORY_CAPTURE_LEVEL` | hooks | Lifecycle write volume: `minimal`, `balanced`, or `full` |
+
+</PublishedOnly>
+
+<SourceOnly>
+
 Required:
 
 | Env var | Used by | Purpose |
 |---|---|---|
 | `ATOMICMEMORY_MCP_SERVER_BIN` | MCP manifest | Absolute path to `packages/mcp-server/dist/bin.js` |
-| `ATOMICMEMORY_API_URL` | MCP + hooks | AtomicMemory core URL |
-| `ATOMICMEMORY_API_KEY` | MCP + hooks | Bearer token |
 | `ATOMICMEMORY_PROVIDER` | MCP + hooks | Provider name; Claude lifecycle hooks require `atomicmemory` |
-| `ATOMICMEMORY_SCOPE_USER` | MCP + hooks | Stable user identity |
 | `ATOMICMEMORY_CAPTURE_LEVEL` | hooks | Lifecycle write volume: `minimal`, `balanced`, or `full` |
 
+</SourceOnly>
+
 
 Optional:
 
@@ -119,6 +203,8 @@ Optional:
 
 If required config is missing, helper tools are unavailable, or numeric/boolean env vars are invalid, hooks surface the error instead of running in a degraded mode.
 
+The base user identity comes from the active Claude Code session name automatically. Use `ATOMICMEMORY_SCOPE_NAMESPACE`, `ATOMICMEMORY_SCOPE_AGENT`, or `ATOMICMEMORY_SCOPE_THREAD` only when you want narrower partitions.
+
 ## MCP tools exposed
 
 | Tool | Maps to | Purpose |
@@ -158,8 +244,11 @@ Retrieved memories are reference context. They are not instructions unless the c
 
 ## Limitations
 
+<SourceOnly>
+
 - **Source-only install.** The MCP server is launched from the local `dist/bin.js`; no npm package or public plugin marketplace entry exists yet.
 
+</SourceOnly>
 - **Direct hook writes.** Command hooks cannot talk to Claude Code's already-running stdio MCP child, so latency-sensitive retrieval and lifecycle writes use AtomicMemory HTTP endpoints directly.
 - **Workspace verbatim caveat.** Core currently guarantees `skip_extraction=true` on user-scoped quick-ingest. Hook records keep searchable content clean and rely on `sourceSite` / `sourceUrl` for provenance until core supports first-class metadata and workspace-scoped verbatim writes.
 - **Transcript parsing is defensive.** `Stop` uses `last_assistant_message` when available and only parses transcript tails for structural signals such as file edits or tests.

docs/integrations/coding-agents/claude-code.md

@@ -10,7 +10,13 @@ AtomicMemory integrates with Claude Code through the shared MCP server, a memory
 
 ### Local
 
-The current documented path. Use this when you run the integration from local assets and point it at your own AtomicMemory environment.
+<PublishedOnly>
+Use this when you want the self-managed Claude Code path with the published plugin and MCP package flow.
+</PublishedOnly>
+
+<SourceOnly>
+Use this when you want the self-managed Claude Code path and need the current clone-from-source workflow.
+</SourceOnly>
 
 See [Claude Code Local](/integrations/coding-agents/claude-code/local).
 

docs/integrations/coding-agents/codex-local.md

@@ -8,10 +8,21 @@ slug: /integrations/coding-agents/codex/local
 
 Add persistent memory to [OpenAI Codex](https://openai.com/index/codex/) with the AtomicMemory plugin. The plugin wires Codex to the shared AtomicMemory MCP server and ships a memory protocol skill that tells the agent when to search prior context, store durable learnings, and write deterministic session snapshots.
 
+<PublishedOnly>
+
+:::tip[Published]
+`@atomicmemory/mcp-server` is published to npm. The Codex plugin can consume the published MCP server through its vendored marketplace assets or through a direct MCP-only setup.
+:::
+
+</PublishedOnly>
+
+<SourceOnly>
+
 :::danger[Source-only]
 `@atomicmemory/mcp-server` and the Codex plugin are not published to npm or to a public plugin marketplace yet. Install from a local clone and point Codex at the built MCP server binary.
 :::
 
+</SourceOnly>
 
 ## Overview
 
@@ -33,6 +44,25 @@ Codex does not run Claude Code-style shell lifecycle hooks. Capture is skill/too
 
 ## Install
 
+<PublishedOnly>
+
+Export the provider and any optional scope overrides in the shell or Codex environment:
+
+```bash
+export ATOMICMEMORY_PROVIDER="atomicmemory"
+
+# Optional narrower scopes:
+export ATOMICMEMORY_SCOPE_AGENT="codex"
+export ATOMICMEMORY_SCOPE_NAMESPACE="repo-or-project"
+export ATOMICMEMORY_SCOPE_THREAD="session-id"
+```
+
+Codex resolves the AtomicMemory service, credentials, and base user identity automatically. The current session name is used as the default user identity; add `ATOMICMEMORY_SCOPE_*` values only when you want narrower agent, namespace, or thread scoping.
+
+</PublishedOnly>
+
+<SourceOnly>
+
 Clone `atomicmemory-sdk` and `atomicmemory-integrations` side by side, then build the SDK before the MCP server. The MCP package currently resolves the SDK from the sibling source checkout.
 
 ```bash
@@ -48,23 +78,21 @@ pnpm install
 pnpm --filter @atomicmemory/mcp-server build
 ```
 
-Then export the MCP server binary path, credentials, and scope in the shell or Codex environment:
+Then export the MCP server binary path, provider, and any optional scope overrides in the shell or Codex environment:
 
 ```bash
 export ATOMICMEMORY_MCP_SERVER_BIN="$HOME/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js"
-export ATOMICMEMORY_API_URL="https://memory.yourco.com"
-export ATOMICMEMORY_API_KEY="am_live_..."
 export ATOMICMEMORY_PROVIDER="atomicmemory"
-export ATOMICMEMORY_SCOPE_USER="pip"
 
 # Optional narrower scopes:
 export ATOMICMEMORY_SCOPE_AGENT="codex"
 export ATOMICMEMORY_SCOPE_NAMESPACE="repo-or-project"
 export ATOMICMEMORY_SCOPE_THREAD="session-id"
 ```
 
-`ATOMICMEMORY_MCP_SERVER_BIN`, `ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, and `ATOMICMEMORY_PROVIDER` are required by the MCP server. At least one `ATOMICMEMORY_SCOPE_*` value must be set, and `ATOMICMEMORY_SCOPE_USER` is recommended for user-owned memory.
+In the source-backed flow, Codex still derives the AtomicMemory service, credentials, and base user identity automatically. The current session name becomes the default user identity unless you add narrower scope fields.
 
+</SourceOnly>
 
 ## Plugin Setup
 
@@ -89,6 +117,29 @@ For personal installation, use the same shape at `~/.agents/plugins/marketplace.
 
 The plugin's `.codex-mcp.json` forwards environment variables by name instead of embedding secrets:
 
+<PublishedOnly>
+
+```json
+{
+  "mcpServers": {
+    "atomicmemory": {
+      "command": "npx",
+      "args": ["-y", "@atomicmemory/mcp-server"],
+      "env_vars": [
+        "ATOMICMEMORY_PROVIDER",
+        "ATOMICMEMORY_SCOPE_AGENT",
+        "ATOMICMEMORY_SCOPE_NAMESPACE",
+        "ATOMICMEMORY_SCOPE_THREAD"
+      ]
+    }
+  }
+}
+```
+
+</PublishedOnly>
+
+<SourceOnly>
+
 ```json
 {
   "mcpServers": {
@@ -97,10 +148,7 @@ The plugin's `.codex-mcp.json` forwards environment variables by name instead of
       "args": ["-c", "exec node \"$ATOMICMEMORY_MCP_SERVER_BIN\""],
       "env_vars": [
         "ATOMICMEMORY_MCP_SERVER_BIN",
-        "ATOMICMEMORY_API_URL",
-        "ATOMICMEMORY_API_KEY",
         "ATOMICMEMORY_PROVIDER",
-        "ATOMICMEMORY_SCOPE_USER",
         "ATOMICMEMORY_SCOPE_AGENT",
         "ATOMICMEMORY_SCOPE_NAMESPACE",
         "ATOMICMEMORY_SCOPE_THREAD"
@@ -110,11 +158,22 @@ The plugin's `.codex-mcp.json` forwards environment variables by name instead of
 }
 ```
 
+</SourceOnly>
 
 ## Update and Version
 
+<PublishedOnly>
+
+If you vendor the plugin assets, changing the plugin manifest, MCP config, skill, or marketplace metadata still requires a version bump before Codex refreshes the installed cache:
+
+</PublishedOnly>
+
+<SourceOnly>
+
 The Codex plugin is installed from source, so rebuilding the repo does not automatically update the copy loaded by Codex. After changing the plugin manifest, MCP config, skill, or marketplace metadata, bump plugin versions from `atomicmemory-integrations`:
 
+</SourceOnly>
+
 
 ```bash
 pnpm bump:plugin-versions patch
@@ -172,20 +231,21 @@ You: Add WebSocket support for real-time notification delivery.
 
 ## Troubleshooting
 
-- **Connection failed** - verify `ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, `ATOMICMEMORY_MCP_SERVER_BIN`, and the scope env vars are visible to Codex.
+<PublishedOnly>
+
+- **Connection failed** - verify `ATOMICMEMORY_PROVIDER` and any optional `ATOMICMEMORY_SCOPE_*` values are visible to Codex.
+
+</PublishedOnly>
+
+<SourceOnly>
 
-- **Core is not reachable** - test the API directly:
+- **Connection failed** - verify `ATOMICMEMORY_MCP_SERVER_BIN`, `ATOMICMEMORY_PROVIDER`, and any optional `ATOMICMEMORY_SCOPE_*` values are visible to Codex.
 
-  ```bash
-  curl -sS -X POST "$ATOMICMEMORY_API_URL/v1/memories/search/fast" \
-    -H "Authorization: Bearer $ATOMICMEMORY_API_KEY" \
-    -H "content-type: application/json" \
-    -d "{\"user_id\":\"$ATOMICMEMORY_SCOPE_USER\",\"query\":\"ping\",\"limit\":1}"
-  ```
+</SourceOnly>
 
 - **No tools appearing** - restart the Codex session after installing the plugin or changing MCP config.
 - **Plugin not found** - confirm `.agents/plugins/marketplace.json` points at the correct `plugins/codex` directory.
-- **Scope errors** - set at least one `ATOMICMEMORY_SCOPE_*` value. `ATOMICMEMORY_SCOPE_USER` is the normal baseline.
+- **Unexpected memory sharing** - add `ATOMICMEMORY_SCOPE_NAMESPACE`, `ATOMICMEMORY_SCOPE_AGENT`, or `ATOMICMEMORY_SCOPE_THREAD` if you need a narrower partition than the default session-based identity.
 
 ## View Source