diff --git a/docs/core-concepts.md b/docs/core-concepts.md index 007484a..5af9c08 100644 --- a/docs/core-concepts.md +++ b/docs/core-concepts.md @@ -4,37 +4,64 @@ sidebar_position: 3 # Core Concepts -NeatContext assembles the context an LLM uses from four building blocks, and -scopes that context **per chat tab**. This page explains each piece and how they -combine. (Each has a full [feature page](/category/features) as well.) +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.) -## The chat tab is the unit of context +## NeatContext runs no model -Every chat lives in its own **tab**, and each tab carries its own: +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. -1. attached **domain profiles** (one of them **active**), -2. attached **knowledge folders**, +When you connect a client, NeatContext exposes a small, read-only local MCP +server. The client calls **`get_context`** and receives **pointers, not content**: -while sharing the workspace-wide pieces: +- the **domain profile file paths** to read, +- the **knowledge folder paths** to search, and +- the **extension tools** available on this connection. -3. enabled **extensions**, and -4. your configured **model**. +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. -When you ask a question, NeatContext gives the model the tab's active profile as -steering context, searches the tab's knowledge folders for grounded evidence, and -offers the enabled extensions' tools so the model can query your real systems. +## The Library holds reusable resources -Because context is per-tab, changing it never means swapping things in and out: -keep *Team A's* profile and runbooks in one tab and *Team B's* in another, and -flip between them. Same tools, same data, different reasoning. +The **[Library](./features/library.md)** is your local registry of reusable +resources: -![Two tabs, each with its own team context](/img/features/chat-tabs.png) +- **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 active profile -steers the model toward *that* team's correct behavior. +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: @@ -70,21 +97,23 @@ Profiles are plain Markdown you own and version however you like. ## Knowledge bases A **knowledge base** is a local folder of documents — typically a team's -**runbooks**, **troubleshooting guides (TSGs)**, and **postmortems**. NeatContext -searches attached folders — in place, locally on your machine — to ground answers -in your material, and cites the documents it used as **clickable sources** under -the answer. +**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. Non-content directories (`.git`, `node_modules`, build outputs) -are skipped automatically. +you already use. → Full details: [Knowledge Bases](./features/knowledge-bases.md) ## Extensions -An **extension** is a connector that gives the model **tools** for your real -systems — read an incident, search logs, list deployments. Each one runs locally -as part of NeatContext, and the model's tool use is always visible in the chat. +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 @@ -93,31 +122,37 @@ 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) -## Your model +## AI clients -NeatContext does **not** provide hosted inference. You configure your own -OpenAI-compatible endpoint (cloud or local) with a base URL, model name, and API -key; requests go directly from your machine to it. To use extension tools, the -model must be **tool-calling capable**. -→ Full details: [Model Provider](./features/model-provider.md) +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 - ┌────────────────────────── Chat tab ──────────────────────────┐ - │ │ -Question │ Active profile + Knowledge folders + Extensions │ - ──────► (how to reason) (what to cite) (tools to call) │ - │ \ | / │ - │ ▼ ▼ ▼ │ - │ Your configured model │ - │ │ │ - └────────────────────────────┼─────────────────────────────────┘ - ▼ - Grounded, team-specific, cited answer + ┌───────────────────── 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 tabs, with two different -profiles and knowledge bases, produce two different — and both correct — -outcomes. +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. diff --git a/docs/extensions/_category_.json b/docs/extensions/_category_.json index ae3ecf1..3bb7ea7 100644 --- a/docs/extensions/_category_.json +++ b/docs/extensions/_category_.json @@ -3,6 +3,6 @@ "position": 6, "link": { "type": "generated-index", - "description": "Write connectors that give the model tools for your own systems, using the Model Context Protocol (MCP)." + "description": "Write connectors that give your AI client tools for your own systems, using the Model Context Protocol (MCP)." } } \ No newline at end of file diff --git a/docs/extensions/api-key-extensions.md b/docs/extensions/api-key-extensions.md index aa8ede6..28c896c 100644 --- a/docs/extensions/api-key-extensions.md +++ b/docs/extensions/api-key-extensions.md @@ -166,8 +166,8 @@ async function searchLogs(args) { if (!query) throw new Error('Tool argument "query" is required.'); // 1. Not connected: no handshake arrived. Return a connection-required - // result — NeatContext stops the tool loop, answers the user with your - // message, and offers a "Connect Acme Logs" button in the chat. + // result — the loop stops and the connected AI client relays your + // message as a "connect Acme Logs first" prompt. if (!connection || !connection.apiKey) { return { error: "acme_logs_not_connected", @@ -225,14 +225,16 @@ don't include them in tool results, and redact them from anything you append to ## 5. Test it -1. **Extensions → Add extension**, select your `acme-logs/` folder, **Enable** it. +1. **Extensions → Add extension**, select your `acme-logs/` folder, **Enable** it, + and select it into a Context. 2. Click **Connect** with the form empty → the inline "API key is required." error appears and nothing is saved. -3. Ask the model something that triggers your tool *before connecting* → the - answer should be your `message` with a **Connect Acme Logs** button. +3. Connect your AI client and ask something that triggers your tool *before + connecting the extension* → the answer should relay your `message` telling you + to connect Acme Logs first. 4. Fill the form, **Connect**, ask again → the tool should call your backend with the key. -5. Enter a wrong key, ask again → the access-denied message and Connect button. +5. Enter a wrong key, ask again → the access-denied message appears. ## Field cheat sheet diff --git a/docs/extensions/building-extensions.md b/docs/extensions/building-extensions.md index dcc798b..68b0143 100644 --- a/docs/extensions/building-extensions.md +++ b/docs/extensions/building-extensions.md @@ -265,11 +265,12 @@ descriptions: 1. In NeatContext, open **Extensions → Add extension** and select your `status-board/` folder. 2. **Enable** it. With `connection: none` there's nothing to authenticate. -3. In a chat with a tool-calling model, ask: *"Is checkout-api healthy right now?"* - The model should call `board_get_service_status` and answer from the result. +3. Select the extension into a Context, connect your AI client, and ask: + *"Is checkout-api healthy right now?"* The client should call + `board_get_service_status` and answer from the result. -If a tool doesn't get called, check that your model is tool-calling capable, that -`tools/list` returns the tool, and that the description makes its purpose obvious. +If a tool doesn't get called, check that `tools/list` returns the tool and that its +description makes its purpose obvious. ## 6. Point it at real systems diff --git a/docs/extensions/create-extension-ui.md b/docs/extensions/create-extension-ui.md index 6777359..4ea06f8 100644 --- a/docs/extensions/create-extension-ui.md +++ b/docs/extensions/create-extension-ui.md @@ -30,7 +30,7 @@ tracker, or any other JSON-over-HTTP service. ## Open the builder -On the **Extensions** page (top bar → Extensions), click **Create**. The +On the **Extensions** page, click **Create**. The builder opens with a step indicator: **Basics → Auth → Data → Review**. Each step validates when you click **Next**, so mistakes surface next to the field that caused them — the same checks the app applies when it generates the @@ -42,7 +42,7 @@ extension. | Field | What to enter | |---|---| -| **Extension name** | A display name, e.g. `GitHub Users`. Shown on the Extensions page and in the chat activity trace; also becomes the generated folder's name (`github-users`). No effect on API calls. | +| **Extension name** | A display name, e.g. `GitHub Users`. Shown on the Extensions page and in the Context activity log when the tool runs; also becomes the generated folder's name (`github-users`). No effect on API calls. | | **Base URL** | The address of the API: scheme + host, plus an optional path prefix — `https://api.github.com`, or e.g. `https://api.example.com/v2`. Every tool call requests **Base URL + Endpoint path** (Step 3). Must be http(s); a trailing slash is removed for you. | | **Description** | Optional. A short note shown on the extension's card, e.g. `Look up GitHub user profiles`. | @@ -125,11 +125,12 @@ card enabled. 1. If the extension needs credentials, fill the **Connect** form (API key) or click **Connect** (OAuth) on its card. -2. Ask something in chat that needs the tool: +2. Select the extension into a Context, connect your AI client, and ask something + that needs the tool: > What company does the GitHub user torvalds work for? - The activity trace shows `github_get_user` running, and the answer comes + The Context's activity log shows `github_get_user` running, and the answer comes from the live API response. ## Growing beyond the builder diff --git a/docs/extensions/manifest-reference.md b/docs/extensions/manifest-reference.md index 9591939..287d608 100644 --- a/docs/extensions/manifest-reference.md +++ b/docs/extensions/manifest-reference.md @@ -196,7 +196,7 @@ model retry: | Result shape | Effect | |---|---| -| `{ "connection_required": true, "provider": "", "message": "…" }` (plus your own `error` code) | Loop stops; `message` becomes the answer; a **Connect <Extension>** button is offered in the chat. Use when credentials are missing or rejected. | +| `{ "connection_required": true, "provider": "", "message": "…" }` (plus your own `error` code) | Loop stops; the connected AI client relays `message` as a "connect it first" prompt instead of guessing. Use when credentials are missing or rejected. | | `{ "error": "_access_denied", "provider": "", "message": "…", "diagnostic_log": "…" }` | Loop stops with the message (and the log path, if given). Use for permission failures while connected. | | `{ "error": "…", "message": "…" }` without those markers | **Not** terminal — the model sees the error and may correct itself (fix a query, choose another tool). Use for ordinary failures. | diff --git a/docs/extensions/overview.md b/docs/extensions/overview.md index f46f291..c2db1a9 100644 --- a/docs/extensions/overview.md +++ b/docs/extensions/overview.md @@ -32,7 +32,7 @@ pages cover [API-key](./api-key-extensions.md) and An extension is a small program that speaks the **Model Context Protocol (MCP)**. It advertises a set of **tools** (each with a name, description, and JSON-Schema input) and executes them when the model calls. NeatContext launches your extension, asks it -what tools it has, and routes tool calls to it during chat. +what tools it has, and routes a connected AI client's tool calls to it. A NeatContext extension is a folder containing: @@ -135,8 +135,8 @@ return a *connection-required* result instead of failing: "provider": "myservice", "message": "Connect MyService before searching logs." } ``` -NeatContext stops the tool loop, shows your `message` as the answer, and renders a -**Connect <Extension>** button in the chat. Rejected credentials +The connected AI client relays your `message` — a "connect it first" prompt — instead +of guessing; connect the extension in NeatContext and the next call works. Rejected credentials (`"error": "myservice_access_denied"`, optionally with `connection_required: true`) behave the same. Ordinary failures (bad query, timeout) should **not** set these fields — the model can then correct itself and retry. The exact contract is in the diff --git a/docs/features/_category_.json b/docs/features/_category_.json index 7ecd042..202f698 100644 --- a/docs/features/_category_.json +++ b/docs/features/_category_.json @@ -3,6 +3,6 @@ "position": 4, "link": { "type": "generated-index", - "description": "A detailed guide to every part of NeatContext — chats and tabs, domain profiles, knowledge bases, model providers, extensions, and your account." + "description": "A detailed guide to every part of NeatContext — Contexts, the Library, domain profiles, knowledge bases, connecting AI clients, extensions, activity logs, and your account." } } diff --git a/docs/features/account.md b/docs/features/account.md index c629272..76c4c22 100644 --- a/docs/features/account.md +++ b/docs/features/account.md @@ -1,12 +1,13 @@ --- -sidebar_position: 6 +sidebar_position: 8 --- # Account The desktop app asks you to **sign in** the first time you open it. Your account -identifies your subscription; your actual working data (profiles, knowledge, -chats, keys) stays local either way. +identifies your subscription; your actual working data (profiles, knowledge +folders, Contexts) stays local either way. NeatContext stores **no model +credential** — there is no model API key to keep. ## Sign in @@ -14,14 +15,15 @@ On first launch you can **create an account** (email + password, confirmed with verification code sent to your inbox) or **sign in** to an existing one. Forgot your password? The reset flow emails you a code. -Once signed in, the top bar shows your plan as a badge next to the account -button. Click it any time to open the **Account** page: +Once signed in, your plan is shown as a badge next to the account entry. Open the +**Account** page any time: ![The Account page](/img/features/account.png) ## Plans -Some workspace limits depend on your plan. For current plans and pricing, see +Some limits depend on your plan — the number of Contexts, knowledge folders per +Context, and enabled extensions. For current plans and pricing, see **[neatcontext.com/pricing](https://www.neatcontext.com/pricing)** — upgrading and managing your subscription is done right from the Account page. diff --git a/docs/features/chats-and-tabs.md b/docs/features/chats-and-tabs.md deleted file mode 100644 index 04efded..0000000 --- a/docs/features/chats-and-tabs.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Chats & Tabs - -Everything in NeatContext happens in a **chat**. Each chat lives in its own **tab** -across the top of the window, and — this is the important part — **each tab carries -its own context**: its own domain profiles and its own knowledge folders. Switch -tabs and you switch the entire working context, not just the conversation history. - -![Chat tabs across the top of the window — here one tab per team](/img/features/chat-tabs.png) - -## The chat workspace at a glance - -![A chat tab with its own profile and knowledge folder attached](/img/features/workspace-context.png) - -- **Tab strip (top)** — one tab per chat, plus a **+** button for a new chat. -- **Sidebar (left)** — the current tab's context: its **Domain Profiles** and its - **Knowledge Base** folders. Whatever you import or add here attaches to the tab - you are on. -- **Top bar** — your model, the **Extensions** page, your account, and the - currently **active profile** for this tab. -- **Conversation + composer (center)** — the messages, and the - *"Message NeatContext"* box at the bottom. Press **Enter** to send - (**Shift+Enter** for a new line). - -:::note[A chat needs a profile] -Sending a message requires the tab to have an **active domain profile** — context -is the point, so NeatContext won't run without at least a minimal one. See -[Domain Profiles](./domain-profiles.md). -::: - -## Creating and naming chats - -Click the **+** at the end of the tab strip to open a new chat. - -A new tab **branches from the tab you were on**: it starts with the same profiles -and knowledge folders attached. That makes the common case fast — continue the -same investigation in a fresh conversation — and the other case easy: detach what -you don't want (the **✕** next to each profile/folder) and attach something else. -Detaching only affects the current tab; every other tab keeps its own setup. - -A chat is titled from your **first message** in it, so tabs stay recognizable -without any manual naming. - -## Reading a response - -When you send a message, NeatContext assembles the tab's context (active profile + -knowledge snippets), sends it to your model, and **streams** the answer live. Along -the way you'll see: - -- **Activity steps** above the answer — what the assistant is doing right now: - reasoning steps and each **tool call** it makes (fetching an incident, - searching your knowledge base, …), so tool use is never invisible. -- **Sources** under the answer — when the response drew on your knowledge base, - the documents it used appear as **clickable chips**. Click one to open the cited - file at the cited lines. This is how you verify an answer instead of trusting it. -- **Connect buttons** — if a tool needed a service you haven't connected yet, the - answer ends with a **Connect <Extension>** button that takes you straight - to the fix. - -Want a real example? The -[Incident Analysis walkthrough](../guides/incident-analysis.md) shows a streamed, -tool-calling, source-cited investigation end to end. - -## Controls while a response is streaming - -- The **send button turns into a stop button** (a square). Click it to cut the - response short — useful when you can already see it going in the wrong direction. -- A tab that is busy shows a **pulsing dot**; a tab that finished while you were - elsewhere shows a **"new response" dot**. You can run investigations in several - tabs at once and come back to each result. - -## Edit & resend - -Hover over any of your previous messages and click the **pencil** icon to edit it. -Sending the edited prompt **replaces the conversation from that point on** — the -messages after it are discarded and the model answers the corrected question. -This is usually better than appending "no, I meant…" because the model re-answers -from a clean state. - -## Deleting a chat - -Click the **✕** on the tab. NeatContext asks for confirmation — deleting a chat -discards its conversation and cannot be undone. (The profiles and knowledge -folders it used are *not* deleted; they stay available to other tabs.) - -## One incident, two tabs - -Per-tab context is what makes NeatContext's core trick possible: keep **Team A's -profile + runbooks in one tab** and **Team B's in another**, ask both the same -question, and compare the answers side by side — no swapping context in and out. -The [Incident Analysis walkthrough](../guides/incident-analysis.md) is built -around exactly this. - -:::info[Plan limits] -The number of chats, and of profiles and knowledge folders per chat, depends on -your plan — see [neatcontext.com/pricing](https://www.neatcontext.com/pricing). -::: diff --git a/docs/features/connect-ai-clients.md b/docs/features/connect-ai-clients.md new file mode 100644 index 0000000..945535a --- /dev/null +++ b/docs/features/connect-ai-clients.md @@ -0,0 +1,113 @@ +--- +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. + +## 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**. | + +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). + +## How to connect + +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. + +## 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. + +### Codex CLI + +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. + +### ChatGPT Desktop + +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. + +:::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. +::: diff --git a/docs/features/context-activity.md b/docs/features/context-activity.md new file mode 100644 index 0000000..46731ae --- /dev/null +++ b/docs/features/context-activity.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 7 +--- + +# Context Activity + +Because NeatContext runs no chat of its own, the way you see **what actually +happened** with a Context is its **activity log**. Each Context keeps its own log +of what connected AI clients did with it: sessions opened, context handed off, and +extension tools invoked. + +Open it from a Context's **View activity** action, or from the **Context Activity** +page (which lists every Context; selecting one there only *views* its log and never +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. + +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. + +## Retention + +Logs are stored locally as JSONL files with **bounded retention** — age- and +size-limited, oldest events dropped first. The defaults are **30 days** and +**32 MiB** per Context. You can change both from the page (7 days to forever; +8 / 32 / 128 MiB), and the new policy is applied to disk immediately. + +- **Clear log** empties the current Context's log (two-step confirmation). +- **Open logs folder** reveals the raw JSONL files so they stay inspectable. + +Everything stays on your machine — activity logs are never sent to a NeatContext +server. diff --git a/docs/features/contexts.md b/docs/features/contexts.md new file mode 100644 index 0000000..118b703 --- /dev/null +++ b/docs/features/contexts.md @@ -0,0 +1,91 @@ +--- +sidebar_position: 1 +--- + +# Contexts + +A **Context** is the unit of work in NeatContext: a named workspace that selects a +set of [domain profiles](./domain-profiles.md), [knowledge folders](./knowledge-bases.md), +and [extensions](./using-extensions.md) for one operational scope — and then hands +that selection to the AI client you connect. Each Context lives in its own **tab** +across the top of the window. + +NeatContext runs no chat and no model of its own. A Context is *configuration*, not +a conversation: you build it here, then **connect an AI client** to it and do the +actual work there. See [Connecting AI Clients](./connect-ai-clients.md). + +## The Context page at a glance + +- **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 + Library** control; nothing here is created from scratch — Contexts *select* + resources that live in your [Library](./library.md). +- **Connect this context** — a card per supported AI client (Claude Code, Claude + Desktop, Codex CLI, ChatGPT Desktop) with a **Connect** button and a readiness + hint. +- **View activity** — opens this Context's [activity log](./context-activity.md). + +:::note[Selecting vs. authoring] +You **author** profiles, link knowledge folders, and install extensions in the +**[Library](./library.md)** and **[Extensions](./using-extensions.md)** pages. +On the Context page you only **select** from what already exists there. +::: + +## Creating and naming Contexts + +Click the **+** at the end of the tab strip to add a Context, and rename it to the +scope it covers (e.g. *Payments production*, *Identity platform*). A Context starts +empty; add profiles, folders, and extensions from the Library. + +Because selection is per-Context, changing one Context never disturbs another — +that is what lets one tab be *Payments* and another *Infra* at the same time. + +## Selecting resources + +- **Domain profiles** — **Add from Library**, then click a profile to make it the + **active** one. A Context can hold several profiles but exactly one is active; + the active profile is the primary behavioral guide the connected client reads. +- **Knowledge folders** — **Add from Library** to attach folders the client will + search in place. +- **Extensions** — enable the read-only connectors this Context should offer. Only + enabled, [trusted or installed](./using-extensions.md) extensions are handed off. + +Remove a resource from a Context with its **✕** — this only detaches it from *this* +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 +[Connecting AI Clients](./connect-ai-clients.md). + +Two important behaviors: + +- **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. + +## One incident, two Contexts + +Per-Context selection is what makes NeatContext's core trick possible: keep **Team +A's profile + runbooks in one Context** and **Team B's in another**, connect a +client to each, and ask both the same question — each correctly reaches its own +right action, with no swapping context in and out. The +[Incident Analysis walkthrough](../guides/incident-analysis.md) is built around +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. + +:::info[Plan limits] +The number of Contexts, and of knowledge folders and enabled extensions per +Context, depends on your plan — see +[neatcontext.com/pricing](https://www.neatcontext.com/pricing). +::: diff --git a/docs/features/domain-profiles.md b/docs/features/domain-profiles.md index 49fdd85..4cf945d 100644 --- a/docs/features/domain-profiles.md +++ b/docs/features/domain-profiles.md @@ -1,50 +1,55 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # Domain Profiles -A **domain profile** is a Markdown file that tells the model how *your* team (or +A **domain profile** is a Markdown file that tells your AI how *your* team (or service, or domain) thinks: what it owns, what it checks first, and what it must -never do. The **active** profile of a chat tab is injected into every request as -steering context — it is the single highest-leverage piece of context you can add. +never do. It is the single highest-leverage piece of context you can add — the +**active** profile of a [Context](./contexts.md) is what the connected AI client +reads first and treats as its primary behavioral guide. -## Create or import a profile +## Create or link a profile in the Library -The **Domain Profiles** section in the sidebar has two buttons: +Profiles live in your **[Library](./library.md)**. Open **Library → Domain +profiles**: -- **New** — creates a fresh profile with a starter template (*Purpose*, +- **New** — creates a fresh profile from a starter template (*Purpose*, *First Checks*, *Dangerous Actions*) and opens it in the editor. The file is - stored in NeatContext's own data folder. -- **Import** — picks an existing `.md` / `.markdown` file from disk. The file + stored under NeatContext's personal Library. +- **Import** — links an existing `.md` / `.markdown` file from disk. The file **stays where it is** — NeatContext references it in place, so you can keep profiles in a git repo and share them with your team. Edits you make in NeatContext's editor are saved back to that same file. -Either way, the profile attaches to the **current chat tab** and appears in the -sidebar list. +A **Team Library** can also share read-only profiles; they appear in the list with +a team origin. See [The Library](./library.md). -:::tip[Profiles are per-tab] -Importing a profile attaches it to the tab you're on. Other tabs are untouched — -that's what lets one tab be "Payments" and another "Infra". The **✕** next to a -profile detaches it from the current tab only; the file on disk is unaffected. -::: +## Select it into a Context + +A profile only steers an answer once it is selected into a Context. On the +**Contexts** page, under **Domain profiles**, choose **Add from Library** and pick +the profile, then click it to mark it **active**. -## Make it active +A Context can hold several profiles but exactly **one is active** — the active +profile is what the client reads as its guide; the others are attached and ready to +switch to. The **✕** detaches a profile from *this* Context only; the file on disk +and its Library entry are unaffected. -A tab can have several profiles attached, but exactly **one is active** — the one -marked *"Active in this chat"* and shown in the top bar. Click a profile in the -sidebar to make it the active one. The active profile is what steers the model; -the others are just attached and ready to switch to. +:::tip[Profiles are per-Context] +Selecting a profile attaches it to the Context you're on. Other Contexts are +untouched — that's what lets one Context be "Payments" and another "Infra". +::: ## Edit a profile -Double-click a profile (or click its **pencil** icon) to open the editor: +Open a profile in the editor (from the Library) to change it: ![The domain profile editor: metadata on top, raw Markdown below](/img/features/profile-editor.png) - **Name** and **Markdown file path** at the top. -- The **raw Markdown** below — what you see is exactly what the model gets. +- The **raw Markdown** below — what you see is exactly what the client reads. - **Save** writes to the profile's file; **Duplicate** copies it as a starting point for a similar team; **Delete** removes it (with confirmation). @@ -94,32 +99,38 @@ Payments Engineering owns the customer-facing payment path: `checkout-api`, - Cite the runbook you relied on. ``` -The `owner` and `criticality` fields are shown in the top bar next to the active -profile. Beyond that, the structure is yours — but **the more concrete your domain -knowledge, the more accurately the model behaves.** Vague guidance produces vague, -improvised answers; specific, spelled-out knowledge produces repeatable, correct -ones. The profiles that work best are explicit about four things: +The `owner` and `criticality` fields are surfaced as profile metadata. Beyond that, +the structure is yours — but **the more concrete your domain knowledge, the more +accurately the AI behaves.** Vague guidance produces vague, improvised answers; +specific, spelled-out knowledge produces repeatable, correct ones. The profiles +that work best are explicit about four things: -1. **Ownership** — what is (and is not) this team's. This is what lets the model +1. **Ownership** — what is (and is not) this team's. This is what lets the AI correctly say *"not ours — hand off"* instead of guessing at a fix. -2. **Investigation order** — the team's first checks, in order. The model will +2. **Investigation order** — the team's first checks, in order. The AI will actually follow them. 3. **Tool usage** — which tools to call, in which situations, and in what order. Don't just list the tools available; tie each one to a trigger and a step, e.g. *"when a deploy is suspected, call `list_recent_deploys` for our services first, then compare timestamps."* Also state when **not** to call a tool. The - more precisely you script this, the more reliably the model calls the right - tool at the right moment instead of improvising. -4. **Guardrails** — dangerous actions, stated as prohibitions. The model repeats - these as warnings at exactly the right moments. + more precisely you script this, the more reliably the AI calls the right tool at + the right moment instead of improvising. +4. **Guardrails** — dangerous actions, stated as prohibitions. The AI repeats these + as warnings at exactly the right moments. The [incident demo's two profiles](https://github.com/XTSoftwareLabs/neatcontext-demo/tree/main/profiles) are complete, realistic examples — including how they wire specific tools into the investigation steps — and are worth copying as a starting point. +:::caution[Keep secrets out of profiles] +A profile is read verbatim by the connected AI client, and is meant to be +version-controlled. Never put credentials in it — extension secrets belong in the +encrypted connection flow, not in a profile file. +::: + ## Where profiles live -Profiles created with **New** are stored by NeatContext for you; imported +Profiles created with **New** are stored in your personal Library; imported profiles remain at their original path (shown in the editor). Either kind is a plain Markdown file you can open, diff, and version like any other text file — there is no lock-in format. diff --git a/docs/features/knowledge-bases.md b/docs/features/knowledge-bases.md index 4fe2aab..a3830b0 100644 --- a/docs/features/knowledge-bases.md +++ b/docs/features/knowledge-bases.md @@ -1,58 +1,59 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- # Knowledge Bases A **knowledge base** is a local folder of documents — typically a team's -**runbooks**, **troubleshooting guides (TSGs)**, and **postmortems** — that -NeatContext searches when answering. It's what turns "an LLM's general opinion" -into "an answer grounded in *your* documents, with citations you can click". +**runbooks**, **troubleshooting guides (TSGs)**, and **postmortems** — that your +connected AI client searches when answering. It's what turns "an LLM's general +opinion" into "an answer grounded in *your* documents, with citations you can +click". -## Add a folder +## Link a folder in the Library -In the sidebar's **Knowledge Base** section, click the **add folder** button and -pick a directory. The folder attaches to the **current chat tab** and is searched -from the next message on. - -![A knowledge folder attached to the current tab](/img/features/sidebar.png) +Knowledge folders live in your **[Library](./library.md)**. Open **Library → +Knowledge folders**, click **Add folder**, and pick a directory. The folder is +**linked in place** — NeatContext reads it where it lives; nothing is copied or +uploaded. A read-only **Team Library** can share folders too. Some useful properties: -- **The folder stays yours.** NeatContext reads it in place — nothing is copied - or uploaded. Keep runbooks in the git repo where they already live; edits are - picked up automatically on the next search. -- **Several folders per tab.** Attach as many as the topic needs (runbooks + - postmortems + architecture notes, say). -- **Per-tab attachment.** Like profiles, folders attach to the tab you're on. - The **✕** detaches a folder from this tab only; other tabs and the folder on - disk are untouched. -- Click a folder's name to see its full path; double-click to reveal it in your - file explorer. +- **The folder stays yours.** Keep runbooks in the git repo where they already + live; edits are picked up automatically on the next search. +- Click a folder's name to see its full path; use its reveal action to open it in + your file explorer. + +## Select it into a Context + +On the **Contexts** page, under **Knowledge folders**, choose **Add from Library** +to attach a folder to the current Context. Attach as many as the topic needs +(runbooks + postmortems + architecture notes, say). The **✕** detaches a folder +from *this* Context only; other Contexts, the Library entry, and the folder on disk +are untouched. ## How it shows up in answers -When your question touches something in an attached folder, the relevant -documents inform the answer, and the ones that were used appear as **clickable -sources** under the response — click one to open the file at the relevant lines. -Searches run **locally on your machine**. +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. Text-based documents work best — Markdown, plain text, logs, JSON, CSV, HTML. -Common non-content directories (like `.git`, `node_modules`, and build outputs) -are skipped automatically, but folders work best when they're focused -documentation folders rather than an entire home directory. +Folders work best when they're focused documentation folders rather than an entire +home directory. ## Tips for a good knowledge base -The documents that work best for NeatContext are the ones that are good for -humans too: +The documents that work best are the ones that are good for humans too: - **Use the real names of things** — service names, error strings, config keys. A runbook that quotes the exact error (`could not obtain connection from pool 'billing-postgres'`) is easy to find the moment that error appears in an incident. - **One topic per file**, with a descriptive filename (`checkout-api-5xx.md` - beats `notes3.md`) — the filename is also what you'll see in the source chips. + beats `notes3.md`) — the filename is also what you'll see in the cited sources. - **Keep postmortems.** They encode "we've seen this before", which is often the fastest route to a diagnosis. @@ -60,6 +61,6 @@ The [incident demo's knowledge folders](https://github.com/XTSoftwareLabs/neatco show the pattern: `runbooks/`, `tsg/`, and `postmortems/` per team. :::info[Plan limits] -The number of knowledge folders per chat depends on your plan — see +The number of knowledge folders per Context depends on your plan — see [neatcontext.com/pricing](https://www.neatcontext.com/pricing). ::: diff --git a/docs/features/library.md b/docs/features/library.md new file mode 100644 index 0000000..a4a9f0e --- /dev/null +++ b/docs/features/library.md @@ -0,0 +1,70 @@ +--- +sidebar_position: 2 +--- + +# The Library + +The **Library** is your local registry of reusable resources — **domain +profiles**, **knowledge folders**, and **extensions**. You *author and link* +resources here once; your [Contexts](./contexts.md) then *select* from them. A +single Library resource can be used by many Contexts, and removing it from a +Context never deletes it from the Library or from disk. + +## Personal resources + +Everything you create or link in the app is **personal** and lives on your +machine: + +- **Domain profiles** — create a new Markdown profile in-app, or **link an + existing `.md` file in place**. Linked profiles stay at their original path, so + you can keep them in a git repo and edit them in NeatContext's editor (edits save + back to the same file). See [Domain Profiles](./domain-profiles.md). +- **Knowledge folders** — **link a folder in place**. NeatContext reads it where it + lives; nothing is copied or uploaded. See [Knowledge Bases](./knowledge-bases.md). +- **Extensions** — bundled connectors, plus any you **Add** or **Create**. See + [Using Extensions](./using-extensions.md). + +## The Team Library (optional, read-only) + +A team can share approved resources through a **Team Library**: any folder that +follows the convention + +```text +/ + profiles/ # shared domain profiles (.md) + knowledge/ # shared knowledge folders + extensions/ # shared extension sources + library.json # marker file identifying the folder as a Team Library +``` + +typically kept as a **git clone**. Connect it from the Library page (and disconnect +it there too). NeatContext treats it as **read-only**: team profiles and folders +are view- and reveal-only, and team extension *sources* stay inert until you +explicitly install them (see below). NeatContext **never writes into the Team +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 + +Profiles and knowledge folders are just files, so they are linked in place. An +extension is **executable code**, so it is handled more carefully: + +- **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. + +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. diff --git a/docs/features/model-provider.md b/docs/features/model-provider.md deleted file mode 100644 index 2c6be0e..0000000 --- a/docs/features/model-provider.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Model Provider - -NeatContext does **not** host or resell a model. You bring your own — a cloud API -key or a local model — and NeatContext orchestrates it: requests go **directly -from the app on your machine to the endpoint you configure**, with your profile -and knowledge assembled in. - -## Open model settings - -Click the **model button** at the left of the top bar (it shows the current model -name, e.g. `gpt-5.4-mini`). That opens the **Model Provider** page: - -![The Model Provider settings page](/img/features/model-provider.png) - -## Fill in the form - -| Field | What to enter | -|---|---| -| **Provider** | Keep **OpenAI-compatible endpoint** — the recommended choice. It covers OpenAI itself and the many services and local runtimes that expose the same API (Azure OpenAI, OpenRouter, Together, vLLM, LM Studio, Ollama, …). | -| **Base URL** | The API root, e.g. `https://api.openai.com/v1`. For a local Ollama server use `http://localhost:11434/v1`. | -| **Model** | The model name as your provider spells it, e.g. `gpt-5.4-mini`. | -| **API key** | Your key. For local servers that don't check keys, enter any non-empty placeholder — the field must not be blank for live calls. | - -Click **Save**. The top bar now shows your model name, and every chat in the -workspace uses this provider. - -:::caution[Pick a tool-calling model] -Extensions only work if the active model supports **function/tool calling** (all -mainstream chat models do). With a non-tool-calling model you still get profiles -and knowledge search, but the model cannot query your systems. -::: - -## How your key is stored - -The API key is encrypted with your **operating system's secure storage** -and saved locally on your machine. It is never written in plaintext, never -committed to profile files, and never sent anywhere except to the provider -endpoint you configured. - -## What happens without a provider - -If no provider is configured (or it fails), chats still work: NeatContext -replies with a placeholder answer that shows the profile and knowledge context -it gathered for your question. It's a handy way to preview your setup — but for -real answers, configure a provider. diff --git a/docs/features/using-extensions.md b/docs/features/using-extensions.md index 7875393..36a44b5 100644 --- a/docs/features/using-extensions.md +++ b/docs/features/using-extensions.md @@ -1,15 +1,18 @@ --- -sidebar_position: 5 +sidebar_position: 6 --- # Using Extensions -**Extensions** give the model **tools**: read an incident, search logs, list -deployments, look up a service. Each extension is a small connector that runs -locally as part of NeatContext. This page is about *using* extensions; to write -your own, see [Building Extensions](../extensions/overview.md). +**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). -Open the page with the **Extensions** button in the top bar: +Open the **Extensions** page from the navigation: ![The Extensions page, with the bundled Datadog and PagerDuty connectors](/img/features/extensions-page.png) @@ -28,30 +31,32 @@ disabled but not removed): They are also reference implementations: click the **folder icon** on either card to open its source. -Independent of extensions, a set of **built-in local tools** is always available -to the model: searching the tab's knowledge folders, reading files from them, and -reading your domain profiles. These are read-only and limited to the folders and -profiles you attached. +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. ## Add an extension 1. Click **Add**. 2. Pick the extension's **folder** — the one containing its `neatcontext-extension.json` manifest. -3. NeatContext **copies** the folder into its own data directory and loads it. - The new card appears in the list, enabled. +3. NeatContext validates the folder and **installs a snapshot** into its own data + directory. 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 the controls: **Enable/Disable**, **open folder**, -and — for extensions you added — **remove**. +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)). :::caution[Extensions are code you run] An extension runs on your machine with your user's permissions. Treat a third-party extension like any code you download: review it before adding (click the folder icon and read the server — good extensions are a single -readable file). Prefer read-only connectors. +readable file). Only bundled first-party connectors are treated as fully trusted; +prefer read-only connectors. ::: ## Connect an extension @@ -73,12 +78,22 @@ 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 handed to the extension only at the moment a tool runs — -never written into its folder. **Disconnect** deletes the stored credentials. +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. -If you ask a question that needs a not-yet-connected extension, the answer will -say so and offer a **Connect** button right in the chat — you don't have to -remember to set things up in advance. +## Enable it and select it into a Context + +Extensions are handed off per Context. Two things have to be true for a connected +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. ## Create your own extension @@ -105,11 +120,10 @@ Extensions page, its folder is openable (a generated one is a nice starting point if you later want to hand-edit it), and secrets go through the normal encrypted connection flow, never into the generated files. -## Extensions in chat +## Seeing extensions in use -Every enabled extension's tools are available to the model in every chat. When -the model uses one, you see it as an **activity step** in the response — tool -use is never invisible. +When a connected client calls an extension tool, the call is recorded in that +Context's [activity log](./context-activity.md) — tool use is never invisible. :::info[Plan limits] The number of enabled extensions depends on your plan — see diff --git a/docs/getting-started.md b/docs/getting-started.md index 349762f..5cb5d9d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,22 +4,27 @@ sidebar_position: 2 # Getting Started -This guide takes you from a fresh install to your first grounded answer, in about -ten minutes. It follows the same shape as a real workspace: sign in, connect a -model, then give a chat a domain profile, a knowledge base, and (optionally) an -extension. +This guide takes you from a fresh install to your first grounded answer — asked +in your own AI client — in about ten minutes. The shape of a real setup is: +sign in, add a domain profile and a knowledge folder to your **Library**, select +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). -- **Your own LLM access** — an API key for an OpenAI-compatible endpoint, or a - local model server. NeatContext does **not** host a model; it orchestrates - yours. Pick a **tool-calling-capable** model if you plan to use extensions. +- **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. - **(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 - *using* extensions needs no Node install — NeatContext runs them on its own - bundled runtime. + *using* the bundled extensions needs no Node install — NeatContext runs them on + its own bundled runtime. ## Step 1 — Sign in @@ -27,59 +32,34 @@ The first time you open NeatContext you're asked to sign in or create an account (email + password; a verification code is emailed to you). Signing in identifies your subscription — your actual work (profiles, knowledge, -chats, API keys) stays on your machine. See [Account](./features/account.md). +Contexts) stays on your machine. See [Account](./features/account.md). ## Step 2 — Take stock of the window -![NeatContext after first launch](/img/features/first-launch.png) +NeatContext opens on the **Contexts** page. The main areas, reachable from the +navigation, are: -Four areas matter: +- **Contexts** — your context workspaces, one per tab. Each Context selects its + own profiles, knowledge folders, and extensions, and has a **Connect this + context** panel with a card per AI client. +- **Library** — your reusable domain profiles, knowledge folders, and extensions. + This is where you *author and link* resources; Contexts just *select* them. +- **Extensions** — install, connect, and manage read-only tool connectors. +- **Context Activity** — a per-Context log of what connected AI clients did. +- **Account** — your sign-in and subscription. -- **Tab strip (top edge)** — one tab per chat. Each tab carries its own context. -- **Sidebar (left)** — this tab's **Domain Profiles** and **Knowledge Base**. - Both are empty on a fresh install; filling them is Steps 4 and 5. -- **Top bar** — the model button (not configured yet), **Extensions**, and - your account. -- **Composer (bottom)** — where you'll type. *Enter* sends, *Shift+Enter* makes - a new line. +## Step 3 — Add a domain profile to your Library -## Step 3 — Connect your model - -1. Click the **model button** at the left of the top bar. -2. Fill in the form — for most providers that's three values: - - | Field | Example | - |---|---| - | Provider | OpenAI-compatible endpoint | - | Base URL | `https://api.openai.com/v1` | - | Model | `gpt-5.4-mini` | - | API key | `sk-…` | - -3. Click **Save**, then **Back**. The top bar now shows your model name. - -![The Model Provider settings page](/img/features/model-provider.png) - -Your key is encrypted with your OS's secure storage and requests go directly -from your machine to this endpoint — no middleman. Local servers (Ollama, LM -Studio, vLLM…) work through their OpenAI-compatible URLs; see -[Model Provider](./features/model-provider.md) for specifics. - -## Step 4 — Add a domain profile - -A [domain profile](./features/domain-profiles.md) tells the model how your team +A [domain profile](./features/domain-profiles.md) tells your AI how your team thinks: what it owns, what to check first, what never to touch. -:::note[This step is required] -A chat needs an **active domain profile** before you can send a message — context -is the whole point, so NeatContext won't run without at least a minimal one. -::: - -1. In the sidebar under **Domain Profiles**, click **New** (starter template, - opens the editor) — or **Import** if you already have a profile `.md` file. -2. Fill in at least three sections: **what you own**, **first checks**, and - **dangerous actions**. Save. -3. Back in the chat, the profile shows *"Active in this chat"* and its name - appears in the top bar. +1. Open **Library → Domain profiles**. +2. Click **New** (starter template, opens the editor) — or **Import** to link an + existing profile `.md` file in place. A linked file **stays where it is**, so + you can keep profiles in a git repo. +3. Fill in at least three sections: **what you own**, **first checks**, and + **dangerous actions**. Make sure the front matter parses (`id`, `name`, + `type`). Save. No profile yet? Start from this minimal template: @@ -106,52 +86,80 @@ owner: My Team - Separate facts from hypotheses, and cite the runbook you relied on. ``` -## Step 5 — Add a knowledge base +## Step 4 — Add a knowledge folder to your Library -Under **Knowledge Base**, click the add-folder button and pick a folder of your -team's docs — runbooks, TSGs, postmortems. NeatContext searches it **in place** -(nothing is copied or uploaded) and cites the documents it uses as clickable -sources under each answer. Details in +Under **Library → Knowledge folders**, click **Add folder** and pick a folder of +your team's docs — runbooks, TSGs, postmortems. NeatContext references it **in +place** (nothing is copied or uploaded); when you connect an AI client, that +client searches the folder itself and cites the documents it uses. Details in [Knowledge Bases](./features/knowledge-bases.md). -![A chat with a profile and knowledge folder attached](/img/features/workspace-context.png) +## Step 5 — Build a Context + +Open **Contexts** and select (or rename) a Context tab. A Context is a named +selection of Library resources for one operational scope. + +1. Under **Domain profiles**, choose **Add from Library** and pick the profile + from Step 3. Mark one profile as **active**. +2. Under **Knowledge folders**, add the folder from Step 4. +3. (Optional) Under **Extensions**, enable any read-only connectors this Context + should offer — see Step 6. + +The Context page shows exactly which profiles, folders, and tools this Context +will hand off, and reminds you that everything stays local until you connect. ## Step 6 — Add an extension (optional but recommended) -Extensions give the model tools for your real systems — read an incident, search -logs, list deployments. Open **Extensions** in the top bar: +Extensions give your AI tools for your real systems — read an incident, search +logs, list deployments. Open **Extensions**: - The bundled **PagerDuty** and **Datadog** connectors are ready to [connect](./features/using-extensions.md#connect-an-extension). - **Add** installs an extension from a folder; **Create** builds a read-only connector for any JSON HTTP API without writing code. -![The Extensions page](/img/features/extensions-page.png) +Enable an extension, then select it into your Context. The +[incident demo](./guides/incident-analysis.md) ships a complete extension plus +three mock systems for it to talk to — the fastest way to see tools in action +without touching production. -The [incident demo](./guides/incident-analysis.md) ships a complete extension -plus three mock systems for it to talk to — the fastest way to see tools in -action without touching production. +## Step 7 — Connect your AI client -## Step 7 — Ask your first question +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). -Type a question your profile and knowledge can answer. For an operational -workspace: +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. + +## 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: ```text Please analyze this incident: . What should we check first, and what's the safe action? ``` -Watch the response: **activity steps** show each tool call as it happens, the -answer **streams** in, and **source chips** underneath link to the exact -documents used. Click a source to verify the answer against your own runbook. +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. + +Back in NeatContext, open **Context Activity** for this Context to see what was +served and which tools ran. ## Where to go next - **[Core Concepts](./core-concepts.md)** — how the pieces combine, in five minutes. +- **[Connecting AI Clients](./features/connect-ai-clients.md)** — what each + supported client does on Connect. - **[Incident Analysis walkthrough](./guides/incident-analysis.md)** — the - centerpiece demo: one incident, two teams, two correct answers. -- **[Features](/category/features)** — every feature in depth. -- **[Building Extensions](./extensions/overview.md)** — connect your own - systems. + centerpiece demo: one incident, two Contexts, two correct answers. +- **[Building Extensions](./extensions/overview.md)** — connect your own systems. diff --git a/docs/guides/datadog-extension.md b/docs/guides/datadog-extension.md index 1b9d824..1ab0bc9 100644 --- a/docs/guides/datadog-extension.md +++ b/docs/guides/datadog-extension.md @@ -5,19 +5,19 @@ sidebar_position: 3 # Using the Datadog Extension NeatContext ships a **built-in Datadog connector** with one read-only tool: -**log search**. The model can pull matching log events — timestamp, status, -service, host, message, tags — while investigating an incident, using the same -query syntax you'd type into the Datadog Log Explorer. It connects with your +**log search**. Your connected AI client can pull matching log events — timestamp, +status, service, host, message, tags — while investigating an incident, using the +same query syntax you'd type into the Datadog Log Explorer. It connects with your **Datadog API and application keys**, and it can only *read* logs: it never writes anything to your Datadog account. This guide walks through getting the keys, connecting, and searching logs from -chat, step by step. +your AI client, step by step. ## Prerequisites -- **NeatContext** installed, with a **tool-calling-capable** model configured - and active (see [Getting Started](../getting-started.md)). +- **NeatContext** installed, and a **supported AI client** installed and signed in + (see [Getting Started](../getting-started.md)). NeatContext brings no model. - A **Datadog account** with logs in it, and permission to create an application key. @@ -45,9 +45,9 @@ open Datadog at: ## Step 2 — Connect on the Extensions page -Open the **Extensions** page from the top bar. Datadog ships bundled, so its -card is already there, marked *Built-in* — nothing to add or install. Make sure -it is **enabled**, then fill the inline form: +Open the **Extensions** page. Datadog ships bundled, so its card is already there, +marked *Built-in* — nothing to add or install. Make sure it is **enabled** (and +select it into the Context you'll connect), then fill the inline form: ![The Datadog card with its inline API-key form](/img/features/extension-datadog-card.png) @@ -107,16 +107,15 @@ Each returned event carries its **timestamp, status, service, host, message** spot the pattern and pivot the investigation. As always in NeatContext, the log evidence lands inside *your* context: the -**domain profile** and the tab's **knowledge folders** (runbooks, TSGs, -postmortems) shape what the model checks first and which actions it recommends. +Context's **domain profile** and its **knowledge folders** (runbooks, TSGs, +postmortems) shape what the AI checks first and which actions it recommends. The [Incident Analysis walkthrough](./incident-analysis.md) shows that combination end-to-end. ## Troubleshooting -- **The answer says Datadog isn't connected**, with a **Connect Datadog** - button in the chat — you asked before connecting. Click the button (or use - the Extensions page) and ask again. +- **The answer says Datadog isn't connected** — you asked before connecting. + Connect Datadog on the Extensions page, then ask again. - **"Datadog denied access (status 401/403)"** — the keys were rejected. In order of likelihood: the **site** doesn't match your organization (see the caution above), the **application key** lacks the `logs_read_data` diff --git a/docs/guides/incident-analysis.md b/docs/guides/incident-analysis.md index cc52aad..cb8f197 100644 --- a/docs/guides/incident-analysis.md +++ b/docs/guides/incident-analysis.md @@ -4,11 +4,11 @@ sidebar_position: 1 # Incident Analysis Walkthrough -This walkthrough demonstrates the core advantage of NeatContext: **giving an LLM a +This walkthrough demonstrates the core advantage of NeatContext: **giving your AI a team's domain knowledge changes how it investigates an incident.** You will analyze -the *same* incident as two different teams — each in its own chat tab — and watch -it correctly reach two *different* outcomes: one team hands the incident off, the -other finds and fixes the root cause. +the *same* incident as two different teams — each in its own **Context**, connected +to your AI client — and watch it correctly reach two *different* outcomes: one team +hands the incident off, the other finds and fixes the root cause. It uses the open **[NeatContext incident-analysis demo](https://github.com/XTSoftwareLabs/neatcontext-demo)**, @@ -18,7 +18,7 @@ Everything runs on your machine; nothing touches real infrastructure. :::info[Why this matters] Between the two investigations, the **only** things that change are the profile -and the knowledge folder each tab carries. The incident, the tools, and the raw +and the knowledge folder each Context carries. The incident, the tools, and the raw evidence are identical — yet each team arrives at its own correct action. That is the whole point. ::: @@ -47,8 +47,9 @@ The right *action*, though, depends on which team is looking: - **Node.js 18+** — to run the mock systems (`node --version`). - **openssl** — to generate the demo's self-signed TLS cert (ships with Git; standard on macOS/Linux). Check with `openssl version`. -- **NeatContext** installed, with a **tool-calling-capable** model configured and - active (see [Getting Started](../getting-started.md)). +- **NeatContext** installed, and a **supported AI client** installed and signed in + (Claude Code, Claude Desktop, Codex CLI, or ChatGPT Desktop). NeatContext brings + no model — your client brings its own. See [Getting Started](../getting-started.md). ## Step 1 — Get the demo @@ -83,59 +84,55 @@ the extension at them with the matching `NEATCONTEXT_DEMO_*_BASE` variables (see demo README's *Customizing* section). ::: -## Step 3 — Open NeatContext and check your model +## Step 3 — Add and enable the extension -Launch NeatContext. Your active model shows in the top bar; if it doesn't, set it -up now ([Getting Started, Step 3](../getting-started.md#step-3--connect-your-model)). -The workspace starts with a single chat tab — in Steps 5 and 6 each team gets its -own tab, with its own profile and knowledge base: - -![Freshly opened NeatContext — the model button shows your model](/img/demo/03-open-neatcontext.png) - -## Step 4 — Add and enable the extension - -1. Open the **Extensions** page from the top bar. +1. Open the **Extensions** page. 2. Click **Add** and select the demo's **`extension/`** folder (the one containing - `neatcontext-extension.json`). NeatContext copies it into its own data - directory and loads **Ops Demo Systems**. -3. Make sure it's **enabled**. There is nothing to authenticate — it talks - straight to the local mock systems. + `neatcontext-extension.json`). NeatContext installs it as **Ops Demo Systems**. +3. Make sure it's **enabled**. There is nothing to authenticate — it talks straight + to the local mock systems. -It exposes three read-only tools to the model: +It exposes three read-only tools: - `demo_get_incident` — incident details + timeline - `demo_search_logs` — log lines for a service/time window - `demo_list_deployments` — recent deploys (change, owning team, risk, rollback) -![Ops Demo Systems enabled, with its three demo tools](/img/demo/04-extensions.png) +## Step 4 — Link the demo's profiles and knowledge into your Library + +Open **Library**: + +1. Under **Domain profiles**, **Import** both `profiles/payments-team.md` and + `profiles/infra-team.md` (linked in place from the clone). +2. Under **Knowledge folders**, **Add folder** for both `knowledge/payments-team` + and `knowledge/infra-team`. -## Step 5 — Investigate as Team A: Payments Engineering +## Step 5 — Build Team A's Context: Payments Engineering -Each chat tab carries its own profile and knowledge base, so every team gets its -own tab. Whatever you import or add attaches to the tab you're on. +On the **Contexts** page, rename the first Context tab to *Payments* and select: -1. **Import the profile into this tab.** Under **Domain Profiles**, click - **Import** and choose **`profiles/payments-team.md`**. Make it the **active** - profile (it will show *"Active in this chat"*). -2. **Add the knowledge base to this tab.** Under **Knowledge Base**, add the - folder **`knowledge/payments-team`**. +1. **Domain profiles → Add from Library →** `payments-team`, and mark it **active**. +2. **Knowledge folders → Add from Library →** `knowledge/payments-team`. +3. **Extensions →** enable **Ops Demo Systems** for this Context. -This tab now has **only** the Payments profile and **only** its knowledge base — -the model reasons strictly from this team's context: +This Context now carries **only** the Payments profile, **only** its knowledge base, +and the demo tools — so the AI will reason strictly from this team's context. -![The Payments tab: only its own profile and knowledge base](/img/demo/05-payments-workspace.png) +## Step 6 — Connect your AI client and ask (Payments) -3. **Ask, in this tab:** +In **Connect this context**, click **Connect** on your client's card. NeatContext +opens a fresh session pinned to the *Payments* Context; approve the `neatcontext` +tools if prompted. Then ask, in that session: ```text 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 model calls `demo_get_incident`, then -`demo_search_logs` / `demo_list_deployments` (watch the activity steps above the -answer), searches the Payments runbooks, and runs the profile's "is this ours?" -triage: +**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: - the 5xx started **09:02, before** the 09:05 checkout-api deploy → our deploy isn't the trigger; @@ -143,60 +140,55 @@ triage: - the dominant error is `could not obtain connection from pool 'billing-postgres'` → the binding constraint is the **DB connection pool**, which Infra owns. -![The Payments analysis: pool exhaustion owned by Infra — hand off](/img/demo/06-payments-answer.png) - ➡️ **Correct outcome for Payments:** this is **not our root cause — escalate / -hand off to Infra Team**, with the evidence. A good investigation can correctly -end in a hand-off. - -Notice the two levers at work in the screenshot: the answer is **grounded in the -Payments knowledge base** — it cites `checkout-api-5xx.md`, -`service-ownership.md`, and the hand-off postmortem as **clickable sources** — -and the **profile shapes the response**, applying the "is this ours?" triage and -the "don't touch Infra's surface — hand off" rule. - -## Step 6 — Investigate the SAME incident as Team B: Infra Team - -No swapping — **give Infra its own tab** and leave the Payments tab exactly as it -is. - -1. **Open a new tab** with the **+** next to the chat tabs. A new tab branches - from the one you were on, so it starts with Payments' context attached. -2. **Make this tab Infra's.** Click the **✕** on the Payments profile and on the - `payments-team` folder — that detaches them from *this tab only*; the Payments - tab keeps them. Then **Import** **`profiles/infra-team.md`** (make it active) - and add the folder **`knowledge/infra-team`**. - -This Infra tab now searches **only Infra's runbooks**. Click back to the Payments -tab — its profile and knowledge base are still there; each tab remembers its own: - -![The Infra tab with its own profile and knowledge base](/img/demo/07-infra-tab.png) - -3. Ask the **exact same question** with the **same incident URL** as Step 5. - -**What you should see.** Same tools, same data — but now the model owns the root -cause. It zeroes in on the **08:58 pgbouncer `default_pool_size` 100 → 40 -change**, confirms the Postgres primary is healthy (so it's the pool ceiling, not -the database), and gives the fix and next actions: **revert `default_pool_size` -to 100 and RELOAD pgbouncer** (no dropped connections), verify the pool drains -and the 5xx clears, then monitor pool utilization. It **warns not to fail over -the primary** — straight from Infra's TSG. - -![The Infra analysis: the 08:58 pgbouncer pool-size change is the root cause](/img/demo/08-infra-answer.png) - -Flip between the two tabs and compare: **same incident, hand-off in one tab, -root-cause fix in the other.** +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 — +`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: +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. + +## Step 7 — Build Team B's Context and ask the SAME incident + +No swapping — **give Infra its own Context** and leave the Payments Context exactly +as it is. + +1. On the **Contexts** page, click **+** for a new Context and name it *Infra*. +2. Select `infra-team` as the active profile, add `knowledge/infra-team`, and + enable **Ops Demo Systems**. +3. **Connect** your client to the *Infra* Context (a fresh, separate session), and + ask the **exact same question** with the **same incident URL** as Step 6. + +**What you should see.** Same tools, same data — but now the AI owns the root +cause. It zeroes in on the **08:58 pgbouncer `default_pool_size` 100 → 40 change**, +confirms the Postgres primary is healthy (so it's the pool ceiling, not the +database), and gives the fix and next actions: **revert `default_pool_size` to 100 +and RELOAD pgbouncer** (no dropped connections), verify the pool drains and the 5xx +clears, then monitor pool utilization. It **warns not to fail over the primary** — +straight from Infra's TSG. + +Compare the two: **same incident, hand-off in one Context, root-cause fix in the +other.** + +:::tip[Verify what was served] +Back in NeatContext, open each Context's [activity log](../features/context-activity.md) +(**View activity**) to confirm which profile, folders, and tools were actually +handed off and run. +::: ## What the demo proves - **Domain profiles steer reasoning toward the team's correct action.** The only - difference between the tabs is the profile + knowledge folder each carries. - Same incident, same tools, same raw evidence — two right answers. -- **Each tab keeps its own context.** Both investigations stay side by side in - one workspace; nothing was swapped in or out. + difference between the two Contexts is the profile + knowledge folder each + carries. Same incident, same tools, same raw evidence — two right answers. +- **Each Context keeps its own selection.** Both investigations stay side by side; + nothing was swapped in or out. - **The knowledge base grounds the answer.** Each team's runbooks/TSGs/postmortems - give the model team-specific first-checks and *dangerous-action* rules it would - not otherwise know — and the citations let you verify. + 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* real incident/log/deploy systems and it works beyond the demo. diff --git a/docs/guides/pagerduty-extension.md b/docs/guides/pagerduty-extension.md index c204242..e5cdb34 100644 --- a/docs/guides/pagerduty-extension.md +++ b/docs/guides/pagerduty-extension.md @@ -5,27 +5,27 @@ sidebar_position: 2 # Using the PagerDuty Extension NeatContext ships a **built-in PagerDuty connector**: three read-only incident -tools the model can call while you investigate — incident details, related -incidents, and similar past incidents. It connects with **OAuth** (you sign in -through your browser; no API keys to create), and it can only *read*: it never +tools your connected AI client can call while you investigate — incident details, +related incidents, and similar past incidents. It connects with **OAuth** (you sign +in through your browser; no API keys to create), and it can only *read*: it never acknowledges, resolves, or modifies anything in your PagerDuty account. -This guide walks through connecting it and using it in chat, step by step. +This guide walks through connecting it and using it from your AI client, step by step. ## Prerequisites -- **NeatContext** installed, with a **tool-calling-capable** model configured - and active (see [Getting Started](../getting-started.md)). +- **NeatContext** installed, and a **supported AI client** installed and signed in + (see [Getting Started](../getting-started.md)). NeatContext brings no model. - A **PagerDuty account** you can sign into in your browser. Any user that can view incidents is enough — the connection asks only for **read** access. ## Step 1 — Find the PagerDuty card -Open the **Extensions** page from the top bar. PagerDuty ships bundled, so its -card is already there, marked *Built-in* — nothing to add or install. Make sure -it is **enabled**. +Open the **Extensions** page. PagerDuty ships bundled, so its card is already +there, marked *Built-in* — nothing to add or install. Make sure it is **enabled**, +and select it into the Context you'll connect. -The card lists the three tools it gives the model (hover a tool for its +The card lists the three tools it gives your AI client (hover a tool for its description): | Tool | What it does | @@ -81,17 +81,18 @@ Are there incidents related to Q3XYZ12ABC45DE right now? Has incident 4211 happened before? Find similar past incidents. ``` -Watch the **activity steps** above the answer — you'll see each PagerDuty tool -call as it happens; tool use is never invisible. And because this is -NeatContext, the answer is shaped by the **domain profile** and grounded in the -**knowledge folders** attached to the tab: pair the PagerDuty tools with your -team's runbooks and the model triages the incident *your team's* way (see the +Your AI client shows each PagerDuty tool call as it makes it, and the call is also +recorded in the Context's [activity log](../features/context-activity.md); tool use +is never invisible. And because this is NeatContext, the answer is shaped by the +Context's **domain profile** and grounded in its **knowledge folders**: pair the +PagerDuty tools with your team's runbooks and the AI triages the incident *your +team's* way (see the [Incident Analysis walkthrough](./incident-analysis.md) for that pattern end-to-end). ### What each tool accepts -You normally never spell these out — the model fills them in — but knowing the +You normally never spell these out — your AI fills them in — but knowing the knobs helps you phrase requests: - **Incident details** can include or skip the incident's log entries @@ -102,9 +103,8 @@ knobs helps you phrase requests: ## Troubleshooting -- **The answer says PagerDuty isn't connected**, with a **Connect PagerDuty** - button in the chat — you asked an incident question before connecting. Click - the button (or connect on the Extensions page) and ask again. +- **The answer says PagerDuty isn't connected** — you asked an incident question + before connecting. Connect PagerDuty on the Extensions page, then ask again. - **It was working, now it asks to reconnect** — the stored token was revoked or could not be refreshed (e.g. your PagerDuty session was removed by an admin). Click **Connect** again; the browser round trip repairs it. diff --git a/docs/intro.md b/docs/intro.md index 6dd32da..b432ee8 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -12,48 +12,59 @@ Don't want to read the docs first? Clone the demo repo and try NeatContext right away: **[github.com/XTSoftwareLabs/neatcontext-demo](https://github.com/XTSoftwareLabs/neatcontext-demo)**. ::: -NeatContext is a **local-first desktop application** for building the context you -feed to LLM-based tools. Your domain profiles, knowledge folders, model -configuration, and tool connections live on your own machine. NeatContext does not -host a model of its own — it **orchestrates the model you bring** (any -OpenAI-compatible endpoint, cloud or local), grounding it in the knowledge and -tools you give it. +NeatContext is a **local-first desktop application** that organizes your team's +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. -![A NeatContext investigation: tool calls, a grounded answer, clickable sources](/img/demo/06-payments-answer.png) +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. ## Why NeatContext -A general-purpose LLM answers from general knowledge. That is rarely enough for +A general-purpose AI answers from general knowledge. That is rarely enough for real operational work, where the *right* answer depends on **your team's context**: what you own, which runbooks apply, and which actions are dangerous in your environment. -NeatContext lets you assemble that context deliberately, from four building blocks: +NeatContext lets you assemble that context deliberately, from three building +blocks, and serve it to your AI: - **[Domain profiles](./features/domain-profiles.md)** — a Markdown description of a team or domain: what it owns, how it investigates, and its guardrails. - **[Knowledge bases](./features/knowledge-bases.md)** — local folders of runbooks, - TSGs, and postmortems the model searches for grounded, citable answers. -- **[Extensions](./features/using-extensions.md)** — connectors that give the model - tools for your real systems. -- **[Your model](./features/model-provider.md)** — any tool-calling-capable LLM - you configure. - -Each **chat tab** carries its own profile and knowledge, so different teams' -contexts live side by side. The payoff is concrete: give two teams their own tab -for the **same** incident, and each correctly arrives at its **own** right -action — one hands off, the other fixes the root cause. The + TSGs, and postmortems your AI searches for grounded, citable answers. +- **[Extensions](./features/using-extensions.md)** — read-only connectors that give + your AI tools for your real systems (incidents, logs, deployments). + +You group those into a **[Context](./features/contexts.md)** — a named workspace +for one operational scope — then **[connect an AI client](./features/connect-ai-clients.md)** +to it. The payoff is concrete: give two teams their own Context for the **same** +incident, and each correctly arrives at its **own** right action — one hands off, +the other fixes the root cause. The [Incident Analysis walkthrough](./guides/incident-analysis.md) demonstrates exactly this. +## What NeatContext is *not* + +- It is **not** a chat app — you keep working in your existing AI client. +- It does **not** host or resell a model, and it never asks for a model API key. +- It does **not** send your files or incident data to a NeatContext server. + +Your AI client brings its own model; NeatContext brings the private context that +model needs. + ## Where to go next - **[Getting Started](./getting-started.md)** — from install to your first - grounded answer in ten minutes. -- **[Core Concepts](./core-concepts.md)** — how profiles, knowledge, extensions, - and models fit together. -- **[Features](/category/features)** — every feature in depth: chats & tabs, - profiles, knowledge, model setup, extensions. + grounded answer in your AI client, in about ten minutes. +- **[Core Concepts](./core-concepts.md)** — how Contexts, profiles, knowledge, + extensions, and AI clients fit together. +- **[Features](/category/features)** — every feature in depth: Contexts, the + Library, profiles, knowledge, AI-client connections, extensions, and activity. - **[Incident Analysis walkthrough](./guides/incident-analysis.md)** — a full, hands-on demonstration of the advantage. - **[Building Extensions](./extensions/overview.md)** — write your own connector.