Docs: V1 (#3)

* docs: rewrite Mintlify docs with Klarity MCP content

Replace the Mintlify starter placeholder pages with real Klarity MCP
documentation derived from README.md, the klarity-process-context-graph
skill, the tools catalog, and the alpha MCP doc. Adds install pages for
each supported client (Claude, Claude Code, ChatGPT, Codex, Cursor,
Gemini CLI) with both OAuth and API-key paths, a concepts section
covering the Discover→Structure→Improve loop and the three intelligence
layers, how-to guides for the core user stories, a tool reference
organized by purpose, and a limitations page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: add workspace-enable prereq, FAQ, and brand icons

- Add a canonical "Enable the MCP in your workspace" section to
  authentication.mdx (sign-in fails without this) and surface an
  Info callout at the top of every install page pointing back to it.
- Add a FAQ page (docs/faq.mdx) with AccordionGroup covering common
  install/auth gotchas; link from the install callouts.
- Swap install icons from FA placeholders to local brand SVGs in
  docs/images/icons/ (claude, openai, codex, cursor, gemini) so each
  client renders with its actual mark.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: apply Klarity branding (logos, colors, Funnel font)

- Replace Mintlify starter logos with Klarity brand mark from assets/
  (logo light/dark + favicon) sourced from the master 512x512 PNG.
- Swap docs.json colors to the temporary Klarity palette:
  primary #FF6C14 (orange), light #FDCD01 (yellow secondary, used by
  Mintlify for hover/active states), dark #CC5610 (darker orange).
- Wire Funnel Display for headings and Funnel Sans for body via the
  Mintlify fonts block (Google Fonts auto-loads by family name).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: use color Codex mark (cloud + terminal prompt)

Swap the mono Codex SVG for the blue/purple gradient variant from
lobehub icons so the install card matches the actual Codex app icon.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: rename index page title to "Introduction"

Avoid the "Klarity MCP - Klarity MCP" browser-tab duplication on the
home page; the page title now complements the site name instead of
mirroring it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: replace "web client" with "assistant" on client cards

Match how Anthropic and OpenAI position Claude and ChatGPT — both
describe their products as AI assistants. Keeps the cards parallel
with the existing "CLI" / "IDE" labels and drops the more technical
"web client" framing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: tighten concepts, intro, and limitations

- Remove Companion-not-yet-accessible framing from limitations.mdx and
  faq.mdx; clean up the parenthetical and UI-fallback bullet that
  referenced it.
- Rework "Why connect it" on the index: lead with "the MCP does
  everything Klarity Advisor does — and more," keep the "unlock is
  surface area" framing, and emphasize organizational process
  intelligence.
- Link the three intelligence-layer rows in the index's "What you get
  access to" table to their concept pages.
- Restructure concepts: observations belong with the Process Index, not
  with artifacts. Move the observations section into
  concepts/process-index.mdx and rename observations-and-artifacts.mdx
  to concepts/artifacts.mdx (artifacts-only).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: revert index title to "Klarity MCP" for the share card

Accept the "Klarity MCP - Klarity MCP" browser-tab duplication in
exchange for a clean social share card that reads "Klarity MCP"
instead of "Introduction".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: rename observations tool ref and cross-link from process index

- Rename "Observations & changes" tool reference page to "Process
  observations and changes" everywhere it appears (page frontmatter and
  the tool overview table). URL slug unchanged.
- Drop "policies" from the index's "What you get access to" row for the
  Process Index — keep the column tight on the most distinct attributes.
- In the Process Index concept page, add a fourth "drill further" step
  to the Search → fetch → drill loop pointing at on-page observations,
  link the Observations bullet at the top to the same on-page anchor,
  and link to the Process observations and changes tool reference.
- In the Process Index tool reference, mirror the same cross-link:
  add a "drill further" entry to the lookup-tool picker pointing at
  get_process_observations / get_observation_activity_timeline, and
  add a common-chain row for "what actually happens when this runs".

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: fix dark-mode icons, link artifacts, rename observations page

- Replace the embedded prefers-color-scheme SVG approach with a
  custom.css filter:invert(1) rule scoped to Mintlify's .dark class.
  This covers both auto-OS-dark-mode and manual-Mintlify-toggle cases
  for the monochrome OpenAI and Cursor marks; the embedded SVG
  approach only handled OS-level dark mode and conflicted with the
  manual toggle. Revert SVGs to lobehub originals.
- Switch colors.light from yellow (#FDCD01) to a brighter orange
  (#FF8540) so Mintlify's dark-mode primary stays in the Klarity
  orange family instead of going yellow.
- Hyperlink "Linked artifacts" in the Process Index concept page to
  /concepts/artifacts (matching the already-linked observations
  bullet).
- Rename "Process observations and changes" -> "Process observations"
  everywhere the page is referenced (frontmatter, tool overview,
  process index pages). URL slug unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: fix LinkedIn footer URL

Use the canonical klarityai company slug.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: add Security & architecture page

A canonical reference page InfoSec / IT reviewers can be pointed at
directly. Covers integration scope (AI clients vs LLMs, supported
surfaces), architecture (same infra as the Klarity Architect web app,
HTTPS/TLS endpoint), authentication (OAuth + long-lived API key),
authorization (identical to the web app — workspace + per-resource
permissions, no MCP-only bypass), and read-only data scope. Wired
into the Getting Started group after Authentication.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: reframe Context Graph as raw-data layer; expand Deviations

- Reframe Context Graph as the layer that sits beneath the Process
  Index and Process observations: entities, communities, relationships,
  claims, and chunks derived from the underlying artifacts. Querying
  the graph is querying the raw layer the Process Index aggregates.
- Drop the "Start at the Context Graph" entry from intelligence-layers
  "When to start at each layer" — Process Index is the default; the
  graph is a fallback that doesn't need its own starting recipe.
- Remove the integer-id vs resource_key Note from the Context Graph
  tool reference.
- Replace the narrow "negative_deviations is per-observation" section
  on the Process observations tool page with a general Deviations
  section: defines positive and negative deviations per observation,
  then a How-to-use sub-section explaining cross-observation
  deviation analysis (Advisor-native or MCP-stitched).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: reframe Claude/ChatGPT fallback as "If you don't have access"

The old "API key fallback" section pushed users straight to a Bearer
token even when the underlying problem was just that their org hadn't
approved the connector or app yet. Replace it with a more general
"If you don't have access" section that points to the other install
paths (Claude Code, Codex, Cursor, Gemini CLI), each of which supports
OAuth, an API key, or both. Same data and permissions either way.

Also reflect Cursor's OAuth support in the authentication methods
table, the limitations OAuth-coverage line, and the Cursor install
page (Connect button via .well-known/oauth-protected-resource), and
keep the API key path on the Cursor install page as a fallback.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: simplify "If you don't have access" to a single pointer

Drop the enumerated list of clients + auth options on the Claude and
ChatGPT install pages — it duplicates state that lives on the
individual install pages and the quickstart, and would drift if any
client's auth surface changed. One sentence pointing at /quickstart
is enough.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: add Verify section to every install page; update verify prompt

- Add a ## Verify section to claude, chatgpt, codex, and gemini-cli
  install pages so every install path has a post-connect sanity check.
- Replace the generic vendor-onboarding verify prompt with a more
  compelling one focused on finding AI transformation opportunities
  (matches the find-opportunities guide). Updated on all install
  pages and on the FAQ "How do I confirm the MCP is connected?" entry.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: add .claude-plugin/marketplace.json so `/plugin install` resolves

Without this file, `/plugin install klarity@Klarity-AI/klarity-mcp` errors
with "Marketplace not found" because Claude Code resolves the GitHub
owner/repo path by reading `.claude-plugin/marketplace.json` from the repo.

Generated via the existing builder pipeline (so it stays in sync via the
drift check) and covered by a new test that verifies every plugin's
`source` resolves to a real `plugin.json`. Install flow is now:

  /plugin marketplace add Klarity-AI/klarity-mcp
  /plugin install klarity@klarity

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: refresh index intro and description

- Replace "Connect your AI tools..." description with one that leads
  with the inward direction: bring process intelligence into your AI
  tools, understand how work happens, identify opportunities,
  agentify your business.
- Body: "identify recommendations" -> "identify opportunities" for
  alignment with the rest of the docs ("find opportunities" guide).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: lowercase the github org in install commands

GitHub treats org/repo paths as case-insensitive, and `git clone` (which
both `/plugin marketplace add` and `gemini extensions install` call under
the hood) resolves either form. Lowercase is easier to type, so use
`klarity-ai/klarity-mcp` in user-facing install commands. The canonical
`repository` URL in plugin.json / metadata.py stays as `Klarity-AI` to
match GitHub's display canonicalization.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Aditya Thiruvengadam <aditya@klaritylaw.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.claude-plugin/marketplace.json

@@ -0,0 +1,35 @@
+{
+  "name": "klarity",
+  "owner": {
+    "name": "Klarity Intelligence, Inc.",
+    "email": "hello@klarity.ai",
+    "url": "https://www.klarity.ai/"
+  },
+  "metadata": {
+    "description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "klarity",
+      "source": ".",
+      "description": "Bring your organization's processes and operational knowledge into your AI assistant. The Klarity MCP connects to your Klarity workspace so you can query your organization's processes, explore the process index knowledge graph linking processes to systems and teams, and ground answers in how your business actually runs \u2014 not generic guesses.",
+      "version": "1.0.0",
+      "homepage": "https://www.klarity.ai/",
+      "license": "Apache-2.0",
+      "keywords": [
+        "klarity",
+        "mcp",
+        "process-intelligence",
+        "process-index",
+        "context-graph",
+        "knowledge-graph"
+      ],
+      "author": {
+        "name": "Klarity Intelligence, Inc.",
+        "email": "hello@klarity.ai",
+        "url": "https://www.klarity.ai/"
+      }
+    }
+  ]
+}

README.md

@@ -24,33 +24,30 @@ Context Graph traversal. The full skill prompt lives at
 [`skills/klarity-process-context-graph/SKILL.md`](./skills/klarity-process-context-graph/SKILL.md).
 
 ## Install - Claude.ai
-After the plugin is approved into the official Anthropic marketplace (`claude-plugins-official`)
 
 Customize -> Connectors -> Search -> Klarity -> Connect
 
 > (NOTE: your organization might have to approve this connector, and you should be added as a user into Klarity for this to work)
 
 ## Install - ChatGPT
-After the plugin is approved into the official OpenAI App Store
 
 Apps -> Search -> Klarity -> Connect
 
 > (NOTE: your organization might have to approve this app, and you should be added as a user into Klarity for this to work)
 
 ## Install — Claude Code
 
-From a Claude Code session, install directly from this repository:
+From a Claude Code session, add this repository as a marketplace, then install:
 
 ```text
-/plugin install klarity@Klarity-AI/klarity-mcp
+/plugin marketplace add klarity-ai/klarity-mcp
+/plugin install klarity@klarity
 ```
 
-Or, after the plugin is approved into the official Anthropic marketplace
-(`claude-plugins-official`):
-
-```text
-/plugin install klarity
-```
+The `marketplace add` step points Claude Code at this repo's
+[`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json). The
+install step then resolves `klarity@klarity` as plugin `klarity` from
+marketplace `klarity`.
 
 ## Install - Codex
 From your terminal, run the following:
@@ -67,7 +64,7 @@ codex mcp login klarity
 ## Install — Gemini CLI
 
 ```bash
-gemini extensions install https://github.com/Klarity-AI/klarity-mcp
+gemini extensions install https://github.com/klarity-ai/klarity-mcp
 ```
 
 To login:
@@ -92,6 +89,7 @@ to Klarity. the MCP will use whatever authentication is configured by your organ
 |---|---|
 | `klarity_mcp/` | Python package: metadata + builders + CLI for regenerating manifests |
 | `.claude-plugin/plugin.json` | Claude Code plugin manifest (generated) |
+| `.claude-plugin/marketplace.json` | Claude Code marketplace catalog (generated) |
 | `.mcp.json` | Claude Code MCP server config (generated, HTTP transport) |
 | `gemini-extension.json` | Gemini CLI extension manifest (generated) |
 | `skills/klarity-process-context-graph/SKILL.md` | The Klarity skill prompt |
@@ -103,7 +101,7 @@ to Klarity. the MCP will use whatever authentication is configured by your organ
 
 ```bash
 pip install -e ".[dev]"
-python -m klarity_mcp --write     # regenerates the 3 public manifests
+python -m klarity_mcp --write     # regenerates the public manifests
 python -m klarity_mcp --check     # CI-side drift check
 pytest -v
 ```