diff --git a/docs/core-concepts.md b/docs/core-concepts.md index 5af9c08..7086985 100644 --- a/docs/core-concepts.md +++ b/docs/core-concepts.md @@ -4,66 +4,53 @@ sidebar_position: 3 # Core Concepts -NeatContext organizes the context an AI client uses, scopes it **per Context -workspace**, and hands it off over a local MCP connection — **without running a -model of its own**. This page explains each piece and how they combine. (Each has -a full [feature page](/category/features) as well.) - -## NeatContext runs no model - -This is the idea everything else follows from. NeatContext does **not** host a -chat, does **not** call a model, and does **not** store a model API key. It is a -**control center**: you curate context in it, and your existing AI client — Claude -Code, Claude Desktop, Codex CLI, or ChatGPT Desktop — does the reading, -searching, tool-calling, and answer-writing with its own model. - -When you connect a client, NeatContext exposes a small, read-only local MCP -server. The client calls **`get_context`** and receives **pointers, not content**: - -- the **domain profile file paths** to read, -- the **knowledge folder paths** to search, and -- the **extension tools** available on this connection. - -The client then reads those files, searches those folders, and calls those tools -itself. NeatContext never uploads your corpus and never sees the client's model. - -## The Library holds reusable resources - -The **[Library](./features/library.md)** is your local registry of reusable -resources: - -- **Domain profiles** — Markdown files you create in-app or **link in place** - from disk. -- **Knowledge folders** — local folders you link in place. -- **Extensions** — read-only tool connectors (bundled, personally added, or from - a shared team Library). - -A Library resource can be selected by many Contexts. Removing it from a Context -never deletes it from the Library or from disk. An optional **read-only Team -Library** — any folder following the `profiles/` + `knowledge/` + `extensions/` -convention (typically a git clone) — lets a team share approved resources. - -## The Context is the unit of handoff - -A **[Context](./features/contexts.md)** is a named workspace for one operational -scope, shown as a **tab**. Each Context selects its own: - -1. **domain profiles** (one of them **active**), -2. **knowledge folders**, and -3. enabled **extensions**. - -Because context is per-Context, you never swap things in and out: keep *Team A's* -profile and runbooks in one Context tab and *Team B's* in another, and connect a -client to whichever you need. Every AI-client session is pinned to exactly one -Context. - -## Domain profiles - -A **domain profile** is a Markdown file describing a team or domain: what it -owns, how it investigates, and the actions it must not take. The connected client -reads the active profile completely and treats it as its primary behavioral guide. - -Profiles use YAML front matter for metadata, followed by free-form Markdown: +NeatContext is a control center for the context your AI uses. You curate that +context here, then connect the AI client you already work in and ask your +questions there. This page introduces the vocabulary you'll see in the app. + +## What you work with + +- **Domain profile** — a Markdown file describing a team or domain: what it owns, + how it investigates, and what it must never do. +- **Knowledge base** — a local folder of documents (runbooks, TSGs, postmortems) + your AI can search and cite. +- **Extension** — a read-only connector that gives your AI tools for a real system + (incidents, logs, deployments). +- **Library** — where your profiles, knowledge folders, and extensions live so you + can reuse them. +- **Context** — a named workspace, shown as a tab, that selects the profiles, + knowledge folders, and extensions for one job. +- **AI client** — the app you already use to talk to a model (Claude Code, Claude + Desktop, Codex CLI, or ChatGPT Desktop). NeatContext brings no model of its own. + +## How the pieces fit + +1. **Add resources to your [Library](./features/library.md).** Create or link + [domain profiles](./features/domain-profiles.md), link + [knowledge folders](./features/knowledge-bases.md), and install any + [extensions](./features/using-extensions.md) you need. +2. **Build a [Context](./features/contexts.md).** On a Context tab, select the + profiles, knowledge folders, and extensions for the job, and mark one profile + **active**. +3. **[Connect your AI client](./features/connect-ai-clients.md).** Click **Connect** + and ask your question in the session that opens. The answer ends with a + **Sources** list of the files and tools it used, so you can verify it. + +## The Context is the unit + +A **Context** carries its own profiles, knowledge folders, and extensions, so you +never swap things in and out. Keep *Team A's* profile and runbooks in one Context +tab and *Team B's* in another, and connect a client to whichever you need. + +That is what makes NeatContext's core advantage possible: give two teams their own +Context for the **same** incident, and each correctly reaches its **own** right +action — one hands off, the other fixes the root cause. The +[Incident Analysis walkthrough](./guides/incident-analysis.md) shows this end to +end. + +## Anatomy of a domain profile + +A profile is plain Markdown with optional YAML front matter for metadata: ```markdown --- @@ -87,72 +74,7 @@ Infra Team owns the shared infrastructure that product teams build on… - Do not fail over the billing-postgres primary during business hours. ``` -Good profiles are explicit about three things: **what the team owns**, its -**first checks / investigation order**, and its **guardrails** (dangerous -actions). Those sections are what turn a generic model into a team-specific one. - -Profiles are plain Markdown you own and version however you like. -→ Full details: [Domain Profiles](./features/domain-profiles.md) - -## Knowledge bases - -A **knowledge base** is a local folder of documents — typically a team's -**runbooks**, **troubleshooting guides (TSGs)**, and **postmortems**. The -connected AI client searches the attached folders — in place, locally on your -machine — to ground its answer, and cites the documents it used as **clickable -`file://` sources** at the end of the answer. - -Because a knowledge base is just a folder on disk, you keep it in whatever repo -you already use. -→ Full details: [Knowledge Bases](./features/knowledge-bases.md) - -## Extensions - -An **extension** is a read-only connector that gives your AI **tools** for your -real systems — read an incident, search logs, list deployments. Each one is a -local stdio MCP server; when a client is connected, NeatContext advertises the -selected extension's tools on the same connection and **proxies** each call, -injecting the extension's credentials from your OS keychain so the client never -sees a secret. - -Extensions declare how they authenticate, which determines the Connect -experience: nothing to configure, an inline **API-key form** (the bundled -Datadog), or **OAuth in your browser** (the bundled PagerDuty). Credentials are -encrypted with your OS secure storage and stay on your machine. -→ Using them: [Using Extensions](./features/using-extensions.md) · -Building them: [Building Extensions](./extensions/overview.md) - -## AI clients - -You connect one of the supported clients — **Claude Code**, **Claude Desktop**, -**Codex CLI**, or **ChatGPT Desktop** — from the Context page. NeatContext opens -a **fresh, Context-pinned session** with an invocation-scoped or project-scoped -MCP configuration; it never rewrites your global client config. The client brings -its own model. -→ Full details: [Connecting AI Clients](./features/connect-ai-clients.md) - -## How it all fits together - -```text - ┌───────────────────── One Context workspace ──────────────────────┐ - │ │ - │ Active profile + Knowledge folders + Extensions │ - │ (how to reason) (what to cite) (tools to call) │ - └──────────────────────────────┬───────────────────────────────────┘ - │ Connect (local MCP) - ▼ - Your AI client — Claude Code / Claude Desktop / - Codex CLI / ChatGPT Desktop - │ - get_context → reads files, searches folders, calls tools - ▼ - Grounded, team-specific answer with a ## Sources footer -``` - -Edits you make to a connected Context are picked up on the client's **next** -`get_context` call — no reconnect needed. Selecting a different Context tab does -**not** retarget an open session; connect again to open a new session for it. - -The [Incident Analysis walkthrough](./guides/incident-analysis.md) shows this in -action: the same incident and the same tools in two Contexts, with two different -profiles and knowledge bases, produce two different — and both correct — outcomes. +The sections that matter most are **what the team owns**, its **first checks**, and +its **guardrails** (dangerous actions). Those turn a generic answer into a +team-specific one. Full guidance is in +[Domain Profiles](./features/domain-profiles.md). diff --git a/docs/features/connect-ai-clients.md b/docs/features/connect-ai-clients.md index 945535a..48ebbb0 100644 --- a/docs/features/connect-ai-clients.md +++ b/docs/features/connect-ai-clients.md @@ -4,110 +4,52 @@ sidebar_position: 5 # Connecting AI Clients -NeatContext does **not** host or resell a model, and it never asks for a model API -key. Your answers come from the AI client you already use. NeatContext's job is to -hand that client the right context — over a local [MCP](https://modelcontextprotocol.io) -connection — and then get out of the way while the client reads, searches, calls -tools, and writes the answer with **its own** model. +Your answers come from the AI client you already use — NeatContext just hands it +the context you selected. There is no model, base URL, or API key to set up in +NeatContext. ## Supported clients -| Client | How it connects | -|---|---| -| **Claude Code** (CLI) | A fresh `claude` session, MCP passed for that invocation only. | -| **Claude Desktop** | A new session in Claude Desktop's built-in **Claude Code**. | -| **Codex CLI** | A fresh Codex TUI session, MCP passed for that invocation only. | -| **ChatGPT Desktop** | A new chat in ChatGPT Desktop's built-in **Codex**. | +- **Claude Code** (CLI) +- **Claude Desktop** (uses its built-in Claude Code) +- **Codex CLI** +- **ChatGPT Desktop** (uses its built-in Codex) -Each card on a Context's **Connect this context** panel shows a readiness hint — -*Ready to connect*, *…not found* (client not installed), or *Build required* (the -native backend still needs building, only in a source build). +Each client has a card in a Context's **Connect this context** panel, with a +readiness hint: *Ready to connect*, *…not found* (the client isn't installed), or +*Build required* (only in a source build). -## How to connect +![The Connect this context panel on the Context page, with a Connect button on each of the ChatGPT Desktop, Claude Desktop, Codex CLI, and Claude Code CLI cards](/img/features/contexts-page.png) -1. Open **Contexts** and select the Context tab you want to hand off. -2. Attach its domain profiles (mark one active), knowledge folders, and any - trusted read-only extensions. -3. In **Connect this context**, click **Connect** on the client you use. -4. If the client prompts you, **trust** the NeatContext-managed workspace and - **approve** the `neatcontext` MCP tools. -5. Ask your question in the session that opens. - -Every **Connect** opens a **fresh** session — NeatContext does not resume or scan -your past conversations. It never rewrites your global client configuration: -CLI clients get MCP only for that one invocation, and desktop clients get a -project-scoped config inside a NeatContext-managed workspace. - -## What the client receives - -Once connected, the client can call one read-only tool plus one tool per selected -extension tool: - -- **`get_context`** returns the connected Context as **pointers, not content**: - the domain profile file paths to read, the knowledge folder paths to search, and - the extension tools available on this connection — with the instruction to use - them itself. -- **One tool per selected extension tool** (for example `demo_search_logs`), - proxied to that extension's local MCP server with your connection injected from - the OS keychain. The client calls live systems directly but **never sees a - secret**. - -During the MCP `initialize` handshake, NeatContext also supplies its analysis and -output instructions, so the client grounds claims in what it actually read, labels -hypotheses, and ends the answer with a **`## Sources`** section citing the exact -files (as `file://` links with line ranges) and tools it used. - -## Context pinning and live edits - -- **Pinned to one Context.** Sessions launched for the same Context share its - runtime; different Contexts use different runtime and workspace paths, so a later - connection never retargets an earlier session. -- **Live edits.** The MCP server (and, for the desktop clients, a prompt hook) - reread the Context's runtime file, so adding or removing profiles, folders, or - extensions in NeatContext is visible on the client's **next** `get_context` - without reconnecting. -- **Deleted or disconnected Context.** If a Context's runtime is removed, the - client gets an actionable *connect from NeatContext first* message instead of - answering from stale context. +## Connect a client -## The runtime boundary - -The Context runtime file NeatContext writes for a connection contains **only -nonsecret metadata**: profile paths, knowledge-folder paths, allowed extension -commands and tool schemas, and keychain *references*. Extension secrets stay in -your OS keychain and are injected only into the extension process, per call — never -written into a runtime file or exposed to the client. - -## Per-client notes - -### Claude Code - -A fresh `claude` interactive session in a stable per-Context managed workspace -containing only a `UserPromptSubmit` hook; the MCP server is passed via -`--mcp-config` for that invocation. Use `/mcp` inside Claude Code to inspect the -connection and its tools. - -### Claude Desktop - -Opens a new session in Claude Desktop's built-in **Claude Code** surface (not a -plain Claude chat) through a `claude://code/new?folder=…` link. Confirm the folder -and approve the tools when prompted. +1. Open **Contexts** and select the Context tab you want to use. +2. Add its domain profiles (mark one **active**), knowledge folders, and any + extensions. +3. In **Connect this context**, click **Connect** on your client's card. +4. If the client asks, **trust** the folder it opens and **approve** the + `neatcontext` tools. +5. Ask your question in the session that opens. -### Codex CLI +Every **Connect** opens a **new** session — it does not reopen a past +conversation. To use a different Context, select its tab and click **Connect** +again. -A fresh Codex TUI session started with `-C` in a stable per-Context workspace; the -MCP server is supplied through invocation-scoped `-c` overrides. NeatContext never -edits your `~/.codex/config.toml`. Codex applies its normal project-hook trust -review. +## Ask your question -### ChatGPT Desktop +Ask your question normally in the session NeatContext opened. Your AI client reads +the Context's profile, searches its knowledge folders, and calls its extension +tools on its own, then writes an answer that ends with a **`## Sources`** list of +the exact files and tools it used. Open a source to check the answer against your +own document. -Opens a new chat in ChatGPT Desktop's built-in **Codex** host (not a hosted plain -ChatGPT chat) through a `codex://threads/new?path=…` link. Review and trust the -managed workspace, hook, and MCP tools when prompted. +:::tip[Edit a Context without reconnecting] +If you change a connected Context (add a profile, folder, or extension), just ask +your next question — the client picks up the change automatically. You only need to +**Connect** again to start a session for a *different* Context. +::: -:::note[No model configuration, ever] -There is no model provider, base URL, or API key anywhere in NeatContext. If you -expected a "connect your model" step from an older version, it has been removed — -the connected AI client brings the model. +:::note[No model setup] +If you're looking for a "connect your model" step, there isn't one — the connected +AI client brings the model. ::: diff --git a/docs/features/context-activity.md b/docs/features/context-activity.md index 46731ae..c9e3725 100644 --- a/docs/features/context-activity.md +++ b/docs/features/context-activity.md @@ -16,11 +16,9 @@ changes the app's active Context). ## What's recorded - **Sessions opened** — when a client connected to this Context. -- **Context injections** — when the current Context was served to the client - (via `get_context` or the per-prompt hook). -- **Tool calls** — each extension tool the client invoked, with timing and a - **truncated preview**. Full tool payloads are **not** stored by default, and - credentials and sensitive fields are redacted. +- **Context handoffs** — when this Context was handed to the client. +- **Tool calls** — each extension tool the client used, with timing and a short + preview. Full tool payloads aren't stored, and credentials are hidden. This is how you verify a Context: connect a client, ask a question, then read the log to confirm which profiles, folders, and tools were actually served and run. diff --git a/docs/features/contexts.md b/docs/features/contexts.md index 118b703..344c3fc 100644 --- a/docs/features/contexts.md +++ b/docs/features/contexts.md @@ -16,6 +16,8 @@ actual work there. See [Connecting AI Clients](./connect-ai-clients.md). ## The Context page at a glance +![The Context page: a Context's selected profile, knowledge folder, and extension on the left, and the Connect this context panel with a card per AI client on the right](/img/features/contexts-page.png) + - **Tab strip (top)** — one tab per Context, plus a **+** button for a new Context. - **Selection panels** — this Context's **Domain profiles** (one marked *active*), its **Knowledge folders**, and its **Extensions**. Each panel has an **Add from @@ -56,17 +58,18 @@ Context; the resource stays in your Library and on disk. ## Connecting a client to a Context -Every AI-client session is **pinned to exactly one Context**. Click **Connect** on -a client card and NeatContext opens a **fresh** session of that client, wired to a -local MCP server scoped to this Context. Details, and what each client does, are in +In the **Connect this context** panel, click **Connect** on your client's card. A +new session opens for *this* Context. Full steps and what each client does are in [Connecting AI Clients](./connect-ai-clients.md). -Two important behaviors: +Two things to know: -- **Live edits.** If you change a connected Context's selection, the client picks - it up on its **next** `get_context` call — no reconnect needed. -- **No silent retargeting.** Selecting a different Context tab does **not** point an - open session at it. To work in another Context, connect a new session for it. +- **You can edit a connected Context.** Add or remove a profile, folder, or + extension and just ask your next question — the client uses the change with no + reconnect. +- **Switching tabs doesn't switch the session.** Selecting a different Context tab + doesn't change an open session. To work in another Context, click **Connect** on + it to open a new session. ## One incident, two Contexts @@ -79,10 +82,9 @@ exactly this. ## Deleting a Context -Click the **✕** on the tab. NeatContext asks for confirmation. Deleting a Context -removes its selection and its activity log, and cleans up its runtime files; the -profiles, folders, and extensions it referenced are **not** deleted — they stay in -your Library for other Contexts. +Click the **✕** on the tab and confirm. Deleting a Context removes its selection +and its activity log. The profiles, folders, and extensions it used are **not** +deleted — they stay in your Library for your other Contexts. :::info[Plan limits] The number of Contexts, and of knowledge folders and enabled extensions per diff --git a/docs/features/knowledge-bases.md b/docs/features/knowledge-bases.md index a3830b0..f8cf008 100644 --- a/docs/features/knowledge-bases.md +++ b/docs/features/knowledge-bases.md @@ -34,11 +34,10 @@ are untouched. ## How it shows up in answers -When you ask a question in a connected client, the client searches the attached -folders **in place, locally on your machine**, and the documents it used are cited -in the answer's **`## Sources`** section — as clickable `file://` links with the -exact line ranges relied on. That's how you verify an answer instead of trusting -it. +When you ask a question in a connected client, the documents it uses are cited in +the answer's **Sources** section — as clickable links to the exact lines. That's +how you verify an answer instead of trusting it. Searches run locally on your +machine. Text-based documents work best — Markdown, plain text, logs, JSON, CSV, HTML. Folders work best when they're focused documentation folders rather than an entire diff --git a/docs/features/library.md b/docs/features/library.md index a4a9f0e..afd0e5c 100644 --- a/docs/features/library.md +++ b/docs/features/library.md @@ -46,25 +46,16 @@ Library** — contributing back is a normal git workflow. Each resource shows its **origin** so you can tell built-in, personal, and team resources apart. -## Extensions have a stricter lifecycle +## Installing extensions -Profiles and knowledge folders are just files, so they are linked in place. An -extension is **executable code**, so it is handled more carefully: +The bundled **PagerDuty** and **Datadog** connectors are ready to use right away. +Any other extension — one you **Add**, **Create**, or that comes from a Team +Library — has to be **installed** before you can use it: open **Library → +Extensions** (or the **Extensions** page) and click **Install**, then review it. +See [Using Extensions](./using-extensions.md). -- **Bundled** extensions ship inside the app and are ready immediately. -- A **personal** or **team** extension folder is a *source location* only. It - becomes callable after you explicitly **install** it — NeatContext validates the - source and copies a snapshot into app-managed storage. -- Source changes are reported, but an **Update / Reload** must explicitly replace - the installed snapshot before new code runs. +## Your files stay yours -This is why an extension you add is trusted narrowly: only bundled first-party -extensions on NeatContext's allowlist are treated as fully trusted; everything else -runs as the read-only connector you reviewed and installed. - -## Where things live - -Personal profiles and knowledge folders are linked by reference and recorded in -NeatContext's local machine state — the files themselves stay wherever you put -them. Installed extension snapshots live in NeatContext's app data. Nothing in the -Library is uploaded to a NeatContext server. +Linked profiles and knowledge folders stay wherever you put them on disk — the +Library just points to them. Nothing in the Library is uploaded to a NeatContext +server. diff --git a/docs/features/using-extensions.md b/docs/features/using-extensions.md index 36a44b5..064084a 100644 --- a/docs/features/using-extensions.md +++ b/docs/features/using-extensions.md @@ -6,11 +6,10 @@ sidebar_position: 6 **Extensions** give your AI **tools**: read an incident, search logs, list deployments, look up a service. Each extension is a small read-only connector that -runs locally as part of NeatContext. When you [connect an AI client](./connect-ai-clients.md) -to a Context, NeatContext advertises that Context's enabled extension tools on the -same connection and **proxies** each call — the client calls your systems directly -but never sees a secret. This page is about *using* extensions; to write your own, -see [Building Extensions](../extensions/overview.md). +runs locally. Enable an extension and select it into a Context, and your connected +AI client can use its tools — with your credentials kept encrypted on your machine, +never exposed to the client. This page is about *using* extensions; to write your +own, see [Building Extensions](../extensions/overview.md). Open the **Extensions** page from the navigation: @@ -31,25 +30,22 @@ disabled but not removed): They are also reference implementations: click the **folder icon** on either card to open its source. -Beyond extensions, the connected AI client reads your selected profiles and -searches your selected knowledge folders with **its own** file and search tools — -NeatContext just hands it the paths. +Beyond extensions, your connected AI client also reads the Context's domain +profiles and searches its knowledge folders — those need no setup here. ## Add an extension 1. Click **Add**. 2. Pick the extension's **folder** — the one containing its `neatcontext-extension.json` manifest. -3. NeatContext validates the folder and **installs a snapshot** into its own data - directory. The new card appears in the list. +3. Review and **install** it. The new card appears in the list. ![A user-installed extension card with its tools listed](/img/features/extensions-with-demo.png) Each card shows the extension's name, description, version, its **tools** (hover one for its description), and controls: **Enable/Disable**, **open folder**, and — -for extensions you added — **remove**. An extension folder is a *source location*; -its installed snapshot is what actually runs, so a later change to the source needs -an explicit **Update / Reload** before new code runs (see [The Library](./library.md)). +for extensions you added — **remove**. If you change an extension's files later, +use its **Update** button to pick up the change. :::caution[Extensions are code you run] An extension runs on your machine with your user's permissions. Treat a @@ -77,10 +73,8 @@ card adapts: ![The PagerDuty card: connect through the provider's sign-in page](/img/features/extension-pagerduty-card.png) -Either way, credentials are **encrypted with your OS secure storage**, stay on -your machine, and are injected into the extension only at the moment a tool runs — -never written into its folder and never exposed to the AI client. **Disconnect** -deletes the stored credentials. +Either way, credentials are **encrypted and stay on your machine**, and are never +exposed to the AI client. **Disconnect** deletes the stored credentials. ## Enable it and select it into a Context @@ -90,10 +84,9 @@ client to see an extension's tools: 1. The extension is **enabled** on the Extensions page. 2. It is **selected** into the Context under **Extensions** on the Context page. -If your AI client asks a question that needs a not-yet-connected extension, the -extension returns a *connection-required* result and the client relays a "connect -it first" message instead of guessing — connect it in NeatContext, and the next -call works. +If you ask something that needs an extension you haven't connected yet, your AI +client will tell you to connect it first. Connect it in NeatContext, then ask +again. ## Create your own extension @@ -111,9 +104,8 @@ There are **two ways** to create an extension: examples. For a full field-by-field walkthrough with a real API, see [Create an Extension in the UI](../extensions/create-extension-ui.md). -2. **Write one yourself (code)** — a single Node script speaking MCP gives you - multiple tools and custom logic. See - [Building Extensions](../extensions/overview.md). +2. **Write one yourself (code)** — a single Node script gives you multiple tools + and custom logic. See [Building Extensions](../extensions/overview.md). Either way the result installs like any other extension: it appears on the Extensions page, its folder is openable (a generated one is a nice starting diff --git a/docs/getting-started.md b/docs/getting-started.md index 5cb5d9d..d7a06dd 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -12,14 +12,11 @@ them into a **Context**, then **connect** the AI client you already use. ## Prerequisites - **The NeatContext desktop app** — installed and able to open (Windows or macOS). -- **A supported AI client, installed and signed in** — one of: - - **[Claude Code](./features/connect-ai-clients.md#claude-code)** (CLI) - - **[Claude Desktop](./features/connect-ai-clients.md#claude-desktop)** (uses its built-in Claude Code) - - **[Codex CLI](./features/connect-ai-clients.md#codex-cli)** - - **[ChatGPT Desktop](./features/connect-ai-clients.md#chatgpt-desktop)** (uses its built-in Codex) - - NeatContext brings **no model** — your AI client brings its own. There is no - API key to enter in NeatContext. +- **A supported AI client, installed and signed in** — one of Claude Code, Claude + Desktop, Codex CLI, or ChatGPT Desktop (see + [Connecting AI Clients](./features/connect-ai-clients.md)). NeatContext brings + **no model** — your AI client brings its own, so there is no API key to enter in + NeatContext. - **(Optional) Node.js 18+** — only if you plan to run the [incident demo](./guides/incident-analysis.md)'s mock systems or [develop your own extensions](./extensions/building-extensions.md). Just @@ -125,31 +122,29 @@ without touching production. ## Step 7 — Connect your AI client -On the Context page, find the **Connect this context** panel and click **Connect** -on the card for the client you use (Claude Code, Claude Desktop, Codex CLI, or -ChatGPT Desktop). +1. On the Context page, find the **Connect this context** panel. +2. Click **Connect** on the card for the client you use (Claude Code, Claude + Desktop, Codex CLI, or ChatGPT Desktop). +3. A new session of that client opens. If it asks, **trust** the folder it opens + and **approve** the `neatcontext` tools. -NeatContext opens a **fresh session** of that client, pinned to this Context, and -starts a local MCP server it can reach. Approve the NeatContext tools if your -client prompts you. No model configuration happens on the NeatContext side — the -client brings its own model. See -[Connecting AI Clients](./features/connect-ai-clients.md) for what each client does. +There is no model to configure — the client brings its own. See +[Connecting AI Clients](./features/connect-ai-clients.md) for what each client +does on Connect. ## Step 8 — Ask your first question, in your AI client -In the session NeatContext just opened, ask a question your profile and knowledge -can answer. For an operational Context: +In the session that just opened, ask a question your profile and knowledge can +answer. For an operational Context: ```text Please analyze this incident: . What should we check first, and what's the safe action? ``` -Your AI client calls NeatContext's `get_context` tool, reads the profile files, -searches the knowledge folders, and calls the extension tools — then writes a -grounded answer that ends with a **`## Sources`** section listing the exact files -(with clickable `file://` links and line ranges) and tools it used. Open a source -to verify the answer against your own runbook. +Your AI client answers using the Context you built, and ends with a **Sources** +list of the files and tools it used. Click a source to check the answer against +your own runbook. Back in NeatContext, open **Context Activity** for this Context to see what was served and which tools ran. diff --git a/docs/guides/incident-analysis.md b/docs/guides/incident-analysis.md index cb8f197..fb754d1 100644 --- a/docs/guides/incident-analysis.md +++ b/docs/guides/incident-analysis.md @@ -129,10 +129,9 @@ Please analyze incident https://localhost:7801/incidents/INC-1001. What should we check first, and what's the safe action? ``` -**What you should see.** The client calls `get_context`, reads the Payments -profile, then calls `demo_get_incident`, `demo_search_logs`, and -`demo_list_deployments`, searches the Payments runbooks, and runs the profile's "is -this ours?" triage: +**What you should see.** The AI reads the Payments profile, calls the demo tools +(`demo_get_incident`, `demo_search_logs`, `demo_list_deployments`), searches the +Payments runbooks, and runs the profile's "is this ours?" triage: - the 5xx started **09:02, before** the 09:05 checkout-api deploy → our deploy isn't the trigger; @@ -144,9 +143,9 @@ this ours?" triage: hand off to Infra Team**, with the evidence. A good investigation can correctly end in a hand-off. -The answer ends with a **`## Sources`** section citing the exact files it read — +The answer ends with a **Sources** section citing the exact files it read — `checkout-api-5xx.md`, `service-ownership.md`, and the hand-off postmortem — as -clickable `file://` links, plus the demo tools it called. Two levers are at work: +clickable links, plus the demo tools it called. Two levers are at work: the answer is **grounded in the Payments knowledge base**, and the **profile shapes the response**, applying the "is this ours?" triage and the "don't touch Infra's surface — hand off" rule. @@ -189,7 +188,7 @@ handed off and run. - **The knowledge base grounds the answer.** Each team's runbooks/TSGs/postmortems give the AI team-specific first-checks and *dangerous-action* rules it would not otherwise know — and the citations let you verify. -- **The extension is just an MCP connector.** Point the same pattern at *your* +- **The extension is a read-only connector.** Point the same pattern at *your* real incident/log/deploy systems and it works beyond the demo. ## Take it further diff --git a/docs/intro.md b/docs/intro.md index b432ee8..ef668fb 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -17,11 +17,10 @@ context and hands it to the AI client you **already work in** — Claude Code, Claude Desktop, Codex CLI, or ChatGPT Desktop. Your domain profiles, knowledge folders, and tool connections live on your own machine. -NeatContext **runs no model of its own**. It hosts no chat, stores no model API -key, and produces no answer. Instead, it serves your selected context to your -AI client over a local [MCP](https://modelcontextprotocol.io) connection; that -client reads your files, searches your folders, calls your tools, and writes the -answer with **its own** model. +You keep working in your AI client — NeatContext just gives it your team's +context so its answers are grounded in *your* runbooks, systems, and rules. There +is no model to configure and no API key to enter: your AI client brings its own +model. ## Why NeatContext diff --git a/static/img/features/contexts-page.png b/static/img/features/contexts-page.png new file mode 100644 index 0000000..087597e Binary files /dev/null and b/static/img/features/contexts-page.png differ