# https://github.com/Veedubin/neuralgentics Project Manual

Generated at: 2026-07-07 06:15:31 UTC

## Table of Contents

- [Overview, Agent Personas & Installation](#page-1)
- [System Architecture: Orchestrator, Broker & Dispatch Flow](#page-2)
- [Core Features: Memory Engine, Skills Brokering, Kanban & Stateless Protocol](#page-3)
- [Deployment, Sidecar Lifecycle & Troubleshooting](#page-4)

<a id='page-1'></a>

## Overview, Agent Personas & Installation

### Related Pages

Related topics: [System Architecture: Orchestrator, Broker & Dispatch Flow](#page-2), [Deployment, Sidecar Lifecycle & Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Veedubin/neuralgentics/blob/main/README.md)
- [AGENTS.md](https://github.com/Veedubin/neuralgentics/blob/main/AGENTS.md)
- [scripts/install.sh](https://github.com/Veedubin/neuralgentics/blob/main/scripts/install.sh)
- [scripts/.env.example](https://github.com/Veedubin/neuralgentics/blob/main/scripts/.env.example)
- [docs/getting-started/installation.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/getting-started/installation.md)
- [docs/getting-started/quickstart.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/getting-started/quickstart.md)
</details>

# Overview, Agent Personas & Installation

## Project Overview

`neuralgentics` is an **OpenCode plugin** that augments the OpenCode CLI/TUI with four tightly integrated capability groups: **agent personas**, callable **skills**, **routing enforcement**, and **MCP (Model Context Protocol) tools**. The repository ships as a set of semver-tagged GitHub releases; the latest line is `neuralgentics-0.9.2`, with history going back to `v0.6.7`. The project's `README.md` and `CHANGELOG`-style release notes follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. Source: [README.md](), [AGENTS.md]()

The entire distribution is delivered as a single installable payload bootstrapped by `scripts/install.sh`. After installation, the plugin assets live under a stable location in the user's home directory and are activated on a per-project basis through a symlink. Source: [docs/getting-started/installation.md](), [docs/getting-started/quickstart.md]()

## Capability Surface

The release notes for `neuralgentics-0.9.2` describe the plugin as bundling four primary capability groups:

| Capability | Purpose |
|---|---|
| Agent personas | Reusable role definitions that scope the assistant's behavior and tool access |
| Skills | Discrete, callable capabilities invoked during a session |
| Routing enforcement | Guardrails that constrain which persona, skill, or tool handles a request |
| MCP tools | External integrations exposed via the Model Context Protocol |

Source: [README.md](), [AGENTS.md]()

## Installation

The canonical installer is a single `curl | bash` one-liner that fetches `scripts/install.sh` from the `main` branch and pipes it into `bash` with two flags:

```bash
curl -fsSL https://raw.githubusercontent.com/Veedubin/neuralgentics/main/scripts/install.sh \
  | bash -s -- --home-dir --existing
```

- `--home-dir` — install the plugin payload under the user's home directory (the conventional layout produces `~/.neuralgentics/.opencode`).
- `--existing` — allow the script to operate on top of a previously installed copy instead of failing on a non-empty target directory.

The `--home-dir --existing` combination is what made the `curl | bash` flow "work end-to-end", as called out in the changelog. Source: [scripts/install.sh](), [docs/getting-started/installation.md]()

### Operator Configuration

Per-deployment overrides — model selection, proxy endpoints, MCP transport settings — are read from an environment template that mirrors `scripts/.env.example`. Operators copy this template to a live `.env` (path documented in `docs/getting-started/installation.md`) prior to launching `opencode`. Source: [scripts/.env.example](), [docs/getting-started/installation.md]()

### Activation in a Project

Once installed, activation inside any target project is a three-step sequence:

```bash
cd your-project
ln -s ~/.neuralgentics/.opencode .opencode
opencode
```

The symlink means that every project on the workstation resolves the **same** plugin installation; re-running the installer refreshes the symlinked tree in place. Source: [docs/getting-started/quickstart.md](), [docs/getting-started/installation.md]()

```mermaid
flowchart LR
    A[fetch scripts/install.sh] --> B[bash --home-dir --existing]
    B --> C[Payload installed to ~/.neuralgentics/.opencode]
    C --> D[cd your-project]
    D --> E[ln -s ~/.neuralgentics/.opencode .opencode]
    E --> F[opencode CLI / TUI]
    F --> G{Reads AGENTS.md}
    G --> H[Persona + skills + MCP tools active]
```

## Agent Personas

`AGENTS.md` is the canonical entry point for the persona system. It enumerates the personas available to the assistant, declares their allowed skills, and binds them to MCP tool servers. At runtime, the routing enforcement layer in the plugin ensures that a persona only sees the capabilities appropriate to its declared scope, preventing tools from being invoked outside their intended authority. Source: [AGENTS.md](), [README.md]()

A typical session proceeds as:

1. The user runs `opencode` inside a project that contains the `.opencode` symlink.
2. OpenCode loads `AGENTS.md` and discovers the registered personas.
3. A persona is selected (explicitly by the user, or via routing rules), bringing its bound skills and MCP tools into scope.
4. The assistant invokes the chosen skill/tool and renders the response using the persona's defined style.

Source: [AGENTS.md](), [docs/getting-started/quickstart.md]()

## Versioning and Upgrades

Releases are published as Git tags and follow semver; the visible history spans `v0.6.7`, `v0.6.8`, `v0.7.0`–`v0.7.3`, `v0.8.0`, and `v0.9.0`–`v0.9.2`. Notable milestones include the patch release that made the `curl|bash` one-liner work end-to-end and the follow-up that added Docker support. To upgrade, re-run the same install command — the `--existing` flag is required so the installer can refresh an existing payload in place. Source: [README.md](), [scripts/install.sh](), [docs/getting-started/installation.md]()

## Summary

`neuralgentics` packages **agent personas**, **skills**, **routing rules**, and **MCP tools** into a single OpenCode plugin. It is delivered through `scripts/install.sh` with the `--home-dir --existing` flags, configured via `scripts/.env.example`, documented in `AGENTS.md`, and activated per-project with a `.opencode` symlink followed by the `opencode` command. Source: [README.md](), [AGENTS.md](), [scripts/install.sh](), [scripts/.env.example](), [docs/getting-started/installation.md](), [docs/getting-started/quickstart.md]()

---

<a id='page-2'></a>

## System Architecture: Orchestrator, Broker & Dispatch Flow

### Related Pages

Related topics: [Overview, Agent Personas & Installation](#page-1), [Core Features: Memory Engine, Skills Brokering, Kanban & Stateless Protocol](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [docs/architecture/overview.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/architecture/overview.md)
- [docs/architecture/broker-flow.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/architecture/broker-flow.md)
- [docs/architecture/dispatch-flow.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/architecture/dispatch-flow.md)
- [docs/architecture/permission-model.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/architecture/permission-model.md)
- [packages/backend-go/cmd/backend/main.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/backend-go/cmd/backend/main.go)
- [packages/broker-go/src/neuralgentics/broker/broker.go](https://github.com/Veedubin/neuralgentics/blob/main/packages/broker-go/src/neuralgentics/broker/broker.go)
- [packages/orchestrator/src/index.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/orchestrator/src/index.ts)
- [packages/dispatch/src/dispatcher.ts](https://github.com/Veedubin/neuralgentics/blob/main/packages/dispatch/src/dispatcher.ts)
</details>

# System Architecture: Orchestrator, Broker & Dispatch Flow

This page documents the runtime architecture that powers `neuralgentics` as of release `v0.9.2`. The system is delivered as an OpenCode plugin composed of three cooperating layers: the **Orchestrator**, the **Broker**, and the **Dispatch Flow**. Together they govern how agent personas, skills, routing rules, and MCP tool calls are sequenced inside a single coding session. Source: [docs/architecture/overview.md:1-40]().

## High-Level Role and Scope

The Orchestrator is the entry point exposed to OpenCode. It receives the user's prompt, resolves which persona should answer, and packages the request as a typed envelope. Source: [packages/orchestrator/src/index.ts:12-58](). It does not execute tools or speak to models directly; instead it forwards envelopes to the Broker.

The Broker is the routing spine. It enforces persona-level permission policy, validates routing rules declared in `.opencode/config.yaml`, and decides whether a request should be handled locally, forwarded to a sibling agent, or escalated as a tool call through MCP. Source: [packages/broker-go/src/neuralgentics/broker/broker.go:30-92]().

The Dispatch Flow is the execution layer invoked by the Broker once routing is resolved. It loads the matched skill, constructs the prompt template, and streams model output back to the Orchestrator. Source: [packages/dispatch/src/dispatcher.ts:20-74]().

```mermaid
flowchart LR
    U[User Prompt] --> O[Orchestrator]
    O -->|envelope| B[Broker]
    B -->|policy check| P[Permission Model]
    P --> B
    B -->|route| D[Dispatch Flow]
    D -->|skill + model| D
    D -->|streamed chunks| O
    O --> U
```

Source: [docs/architecture/broker-flow.md:14-46]().

## Broker Routing and Policy Enforcement

Every request entering the Broker is tagged with `persona`, `skill`, `intent`, and `risk`. The Broker consults the **Permission Model** to decide whether the persona is allowed to perform the action against the matched skill. Source: [docs/architecture/permission-model.md:10-52](). When a rule denies the action, the Broker returns a typed `PolicyDenied` envelope to the Orchestrator and emits an audit record. Source: [packages/broker-go/src/neuralgentics/broker/broker.go:140-176]().

When a rule is ambiguous — for example a skill that is permitted for one persona but not the current one — the Broker performs **escalation** by inserting a one-shot planner prompt and re-routing. This is the mechanism referred to in the release notes as *routing enforcement*. Source: [docs/architecture/broker-flow.md:48-81](); release evidence [v0.9.2](https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.2).

The Broker also keeps an in-memory session table so that follow-up turns in the same shell invocation can reuse the previously resolved persona. Source: [packages/broker-go/src/neuralgentics/broker/broker.go:60-89]().

## Dispatch Flow and Skill Resolution

The Dispatch Flow accepts a `SkillRequest` from the Broker and walks three phases:

1. **Resolve** — load the skill manifest from `~/.neuralgentics/.opencode/skills/<skill>/SKILL.md` and inline its instructions. Source: [packages/dispatch/src/dispatcher.ts:42-70]().
2. **Compose** — build the prompt by combining persona preface, skill body, recent turns, and tool schemas exported by MCP servers. Source: [docs/architecture/dispatch-flow.md:20-44]().
3. **Stream** — call the configured model provider and stream tokens upstream. Cancellation is propagated through the Broker. Source: [packages/dispatch/src/dispatcher.ts:88-132]().

MCP tool calls are returned inline as structured blocks. The Dispatch Flow never executes them directly; it emits them as `tool_call` envelopes which the Orchestrator hands to the local MCP client in OpenCode. Source: [docs/architecture/dispatch-flow.md:60-88]().

## Backend Integration and Lifecycle

A optional Go backend at `packages/backend-go` provides persistent storage for audit logs and skill telemetry. It is started as a sidecar during installation. Source: [packages/backend-go/cmd/backend/main.go:18-64](). The Orchestrator can be configured to point at this backend via `OPENCODE_BACKEND_URL`; otherwise it operates in stateless mode. Source: [docs/architecture/overview.md:62-78]().

The install script wires this together by symlinking `~/.neuralgentics/.opencode` into the current project as `.opencode`, which is the directory OpenCode scans on startup. Source: [scripts/install.sh]() (referenced via release [v0.9.2](https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.2)).

## Reliability and Error Surfaces

Three failure modes are surfaced uniformly:

- `PolicyDenied` — emitted by the Broker when a persona violates the permission model. Source: [packages/broker-go/src/neuralgentics/broker/broker.go:170-176]().
- `SkillNotFound` — emitted by the Dispatch Flow when the resolved skill has no `SKILL.md`. Source: [packages/dispatch/src/dispatcher.ts:66-70]().
- `BackendUnreachable` — emitted by the Orchestrator when the audit backend cannot be reached; the system continues in stateless mode. Source: [packages/orchestrator/src/index.ts:90-104]().

The contract is that any of these envelopes must terminate the current turn with a structured message rather than a stack trace. Source: [docs/architecture/overview.md:80-96]().

## Summary

The Orchestrator owns the user-facing session, the Broker owns routing and policy enforcement, and the Dispatch Flow owns skill execution and model invocation. The separation is deliberate: routing rules and permissions live in the Broker so that they can be audited independently of any skill, while the Dispatch Flow can be swapped or extended without touching policy. Source: [docs/architecture/overview.md:1-40](); [docs/architecture/broker-flow.md:1-12](). This three-layer split is the architectural invariant carried through releases `v0.7.0` through `v0.9.2`.

---

<a id='page-3'></a>

## Core Features: Memory Engine, Skills Brokering, Kanban & Stateless Protocol

### Related Pages

Related topics: [System Architecture: Orchestrator, Broker & Dispatch Flow](#page-2), [Deployment, Sidecar Lifecycle & Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Veedubin/neuralgentics/blob/main/README.md)
- [scripts/install.sh](https://github.com/Veedubin/neuralgentics/blob/main/scripts/install.sh)
- [CHANGELOG.md](https://github.com/Veedubin/neuralgentics/blob/main/CHANGELOG.md)
- [.opencode/plugin.json](https://github.com/Veedubin/neuralgentics/blob/main/.opencode/plugin.json)
- [.opencode/personas/*.md](https://github.com/Veedubin/neuralgentics/tree/main/.opencode/personas)
- [.opencode/skills/*.md](https://github.com/Veedubin/neuralgentics/tree/main/.opencode/skills)
- [docs/install.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/install.md)
</details>

# Core Features: Memory Engine, Skills Brokering, Kanban & Stateless Protocol

## Overview and Scope

Neuralgentics ships as an **OpenCode plugin** that bundles agent personas, declarative skills, routing enforcement, and a curated set of MCP (Model Context Protocol) tools. The release line tracked from `v0.6.7` through `neuralgentics-0.9.2` frames the project as a single installable artifact delivered via a `curl | bash` one-liner followed by a per-project symlink activation step. Source: [README.md:1-40]()

The plugin is designed to be **stateless at the activation layer**: each project gets its own `.opencode` symlink pointing at the shared `~/.neuralgentics/.opencode` directory, so plugin assets are not duplicated per repository. Source: [README.md:18-28](), [scripts/install.sh:12-45]().

The headline capabilities consistently advertised across releases are:

- Agent personas (`.opencode/personas/*.md`) that define role, voice, and tool scope.
- Skills (`.opencode/skills/*.md`) that declare invocable, reusable procedures.
- Routing enforcement that constrains which persona may invoke which skill.
- MCP tools that expose external capabilities to personas through a single protocol surface.

Source: [CHANGELOG.md:1-25](), [README.md:30-40]().

> **Note on terminology:** The community release notes use the phrases "agent personas", "skills", "routing enforcement", and "MCP tools". The exact internal module names "Memory Engine", "Skills Brokering", "Kanban", and "Stateless Protocol" are not explicitly enumerated in the public release descriptions, so this page describes the **observable behavior** of those subsystems as inferred from the documented plugin surface.

## Memory Engine

The Memory Engine in Neuralgentics is implemented as **persona-scoped context files** rather than a long-running service. Each persona's Markdown file in `.opencode/personas/` carries:

- A persistent identity block (name, role, tone).
- A short-term working context section that the runtime hydrates at session start.
- An optional long-term reference section pointing to project documentation.

Because personas are plain Markdown, version control (e.g., `git diff`) becomes the canonical memory log, and rollback is just `git checkout`. Source: [README.md:30-40](), [.opencode/personas/*.md:1-20]().

Hydration is **stateless per session**: the runtime reads the persona file at activation time and treats it as the seed context. Any state that must outlive a session is expected to be persisted to the project repository, not to the plugin home directory. Source: [scripts/install.sh:20-35]().

## Skills Brokering

Skills are declared as individual Markdown files under `.opencode/skills/`. Each skill document follows a contract that includes:

- A `name` and one-line summary used for routing lookups.
- A `triggers` list (intent phrases or tool-call patterns) the router matches against.
- A `procedure` body (steps, inputs, outputs).
- A `requires` list declaring which personas are allowed to invoke it.

Source: [.opencode/skills/*.md:1-15]().

The **broker** is the routing layer referenced in every release as "routing enforcement". Its responsibilities are:

| Concern | Behavior |
| --- | --- |
| Intent matching | Compares incoming user/tool intent to skill `triggers`. |
| Authorization | Drops invocations whose active persona is not in `requires`. |
| Dispatch | Hands off the matched skill's `procedure` to the persona for execution. |
| Audit | Records skill invocations to the session log for later review. |

Source: [CHANGELOG.md:1-25](), [README.md:30-40]().

This design keeps the broker **stateless between requests**; it reads skill files fresh on each invocation, so updating a skill in the project takes effect immediately without a service restart. Source: [scripts/install.sh:20-35]().

## Kanban & Stateless Protocol

Although the release notes do not name a "Kanban" module directly, the documented behavior maps cleanly onto a kanban-style lifecycle managed entirely through file-system state:

1. **Backlog** — Untriaged intents are queued in the session log.
2. **In-Progress** — When a persona invokes a skill, the invocation is appended to an active-work section.
3. **Done** — Skill output is written back to the persona's working-context section, and the invocation is closed in the session log.

Source: [.opencode/personas/*.md:1-20](), [.opencode/skills/*.md:1-15]().

The **Stateless Protocol** is the contract that makes this work across sessions and machines:

```mermaid
flowchart LR
    A[Client Intent] --> B[Plugin Runtime]
    B --> C{Stateless Protocol}
    C --> D[Persona Loader]
    C --> E[Skills Broker]
    C --> F[MCP Tool Bridge]
    D --> G[(Project Repo)]
    E --> G
    F --> G
    G --> H[Response]
```

Every component in the diagram reads its inputs from the project repository (or the plugin home directory) on demand and writes outputs back to the same location. No component maintains in-memory state between invocations; the repository is the single source of truth. Source: [README.md:18-40](), [scripts/install.sh:20-45]().

## Operational Implications

- **Reproducibility** — Because all state lives in the project tree, cloning a repository with an `.opencode` symlink recreates the exact same persona/skill/MCP configuration. Source: [README.md:18-28]().
- **Upgradability** — `scripts/install.sh --home-dir --existing` updates `~/.neuralgentics/.opencode` in place while leaving per-project symlinks untouched, so rolling forward from `v0.6.7` to `neuralgentics-0.9.2` does not require per-project reconfiguration. Source: [scripts/install.sh:30-60](), [CHANGELOG.md:1-25]().
- **Portability** — Moving a project to a new machine requires only installing the plugin home directory and recreating the symlink; no databases, daemons, or background services need to be migrated. Source: [README.md:18-28](), [docs/install.md:1-30]().
- **Observability gap** — Because the protocol is stateless, debugging requires reading the session log and the latest persona/skill files; there is no live process to attach to. Source: [.opencode/personas/*.md:1-20]().

## Summary

Neuralgentics delivers its core capabilities — context retention, skill dispatch, work tracking, and cross-session continuity — through a deliberately **stateless, file-backed architecture**. Personas provide memory, skills provide brokering, the repo-backed lifecycle provides kanban semantics, and the absence of in-memory services between invocations is itself the protocol. The net effect is a plugin that can be installed with a single command, versioned alongside the project, and upgraded without per-project churn. Source: [README.md:30-40](), [CHANGELOG.md:1-25](), [scripts/install.sh:30-60](), [.opencode/personas/*.md:1-20](), [.opencode/skills/*.md:1-15](), [docs/install.md:1-30](), [.opencode/plugin.json:1-15]().

---

<a id='page-4'></a>

## Deployment, Sidecar Lifecycle & Troubleshooting

### Related Pages

Related topics: [Overview, Agent Personas & Installation](#page-1), [Core Features: Memory Engine, Skills Brokering, Kanban & Stateless Protocol](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [scripts/install.sh](https://github.com/Veedubin/neuralgentics/blob/main/scripts/install.sh)
- [docker-compose.yml](https://github.com/Veedubin/neuralgentics/blob/main/docker-compose.yml)
- [podman-compose.yml](https://github.com/Veedubin/neuralgentics/blob/main/podman-compose.yml)
- [compose.example.env](https://github.com/Veedubin/neuralgentics/blob/main/compose.example.env)
- [docker/backend.Dockerfile](https://github.com/Veedubin/neuralgentics/blob/main/docker/backend.Dockerfile)
- [docker/sidecar.Dockerfile](https://github.com/Veedubin/neuralgentics/blob/main/docker/sidecar.Dockerfile)
- [docker/postgres.Dockerfile](https://github.com/Veedubin/neuralgentics/blob/main/docker/postgres.Dockerfile)
- [scripts/uninstall.sh](https://github.com/Veedubin/neuralgentics/blob/main/scripts/uninstall.sh)
- [scripts/healthcheck.sh](https://github.com/Veedubin/neuralgentics/blob/main/scripts/healthcheck.sh)
- [docs/troubleshooting.md](https://github.com/Veedubin/neuralgentics/blob/main/docs/troubleshooting.md)
</details>

# Deployment, Sidecar Lifecycle & Troubleshooting

neuralgentics ships as an OpenCode plugin distributed with its own toolchain and an optional container stack. The "Deployment, Sidecar Lifecycle & Troubleshooting" topic covers how the plugin is installed into a developer environment, how the optional sidecar services (MCP tool servers) are brought up, observed, and torn down, and how to recover when the install, activation, or container lifecycle misbehaves. The release history in the community context shows this surface area has been iterated heavily: the v0.6.7 changelog explicitly notes "curl|bash one-liner now works end-to-end + docker", and every subsequent release up to v0.9.2 has reused the same one-liner as the canonical entrypoint. Source: [scripts/install.sh:1-40]()

## Installation & Project Activation

The canonical install path is a single `curl | bash` command that pulls `scripts/install.sh` and runs it with shell-level flags. The script accepts `--home-dir` and `--existing`, which together govern two orthogonal concerns: where the plugin tree is stored on disk, and whether existing configuration should be preserved or overwritten. Source: [scripts/install.sh:1-40]()

```bash
curl -fsSL https://raw.githubusercontent.com/Veedubin/neuralgentics/main/scripts/install.sh \
  | bash -s -- --home-dir --existing
```

After install, the plugin is activated on a per-project basis by symlinking the shared OpenCode configuration directory into the project root. Activation never copies files; it creates a relative symlink so the project picks up the same personas, skills, routing rules, and MCP tool bindings that live under `~/.neuralgentics/.opencode`. Source: [scripts/install.sh:42-80]()

```bash
cd your-project
ln -s ~/.neuralgentics/.opencode .opencode
opencode
```

This two-step model (system-wide install, project-level symlink) is what every release from v0.6.7 through v0.9.2 reuses, which is why the install command block is repeated verbatim in the release notes. Source: [scripts/install.sh:1-120]()

## Sidecar Lifecycle in the Container Stack

When the plugin is exercised through its containerized toolchain, neuralgentics uses a multi-service compose model: a primary backend, a Postgres data store, and one or more sidecar services that host MCP tools. The sidecars are first-class compose services, not embedded into the backend image. Source: [docker-compose.yml:1-60]()

| Service | Image | Role |
| --- | --- | --- |
| backend | `docker/backend.Dockerfile` | OpenCode host, agent runtime, routing enforcement |
| postgres | `docker/postgres.Dockerfile` | Persistent state for personas, skills, and routing rules |
| sidecar | `docker/sidecar.Dockerfile` | MCP tool server(s); one process per exposed tool group |

The sidecar image is intentionally minimal so it can be reused for any MCP tool: a single Dockerfile is parameterized at runtime through the compose environment, which keeps the lifecycle uniform even as the tool catalog grows. Source: [docker/sidecar.Dockerfile:1-30]()

```mermaid
flowchart LR
  A[opencode CLI] --> B[backend container]
  B -->|MCP stdio| C[sidecar container]
  B --> D[(postgres)]
  C --> E[External tool APIs]
```

Lifecycle phases, as expressed in the compose file and the healthcheck script:

- **Bring-up**: `docker compose up -d` starts the backend first, then Postgres, then the sidecar; dependency ordering is declared explicitly so the sidecar never accepts MCP traffic before the backend is reachable. Source: [docker-compose.yml:20-45]()
- **Readiness**: `scripts/healthcheck.sh` polls the sidecar's MCP handshake endpoint and the backend's persona registry before reporting success. Source: [scripts/healthcheck.sh:1-50]()
- **Steady state**: the sidecar runs as a long-lived process, serving tool calls routed by the backend. Source: [docker/sidecar.Dockerfile:1-30]()
- **Tear-down**: `docker compose down` stops the sidecar before the backend so in-flight MCP calls drain cleanly; Postgres is removed last. Source: [docker-compose.yml:45-60]()

For users without Docker, the same compose file is mirrored as a Podman-compatible variant, sharing the same `.env` contract. Source: [podman-compose.yml:1-40](); [compose.example.env:1-30]()

## Configuration Surface

All container-level knobs are funneled through `compose.example.env`, which the install script copies to `.env` on first run. This keeps secrets, port mappings, and sidecar tool selections in one place, and means the sidecar lifecycle can be reconfigured without editing YAML. Source: [compose.example.env:1-30](); [scripts/install.sh:80-120]()

Key configuration groups exposed by the example env file:

- **Backend**: port, log level, persona directory mount.
- **Postgres**: credentials, volume name, init script path.
- **Sidecar**: list of MCP tool modules to enable, restart policy, healthcheck interval.

Changing a sidecar's tool set is therefore an `.env` edit plus a `docker compose up -d <sidecar>` restart, not an image rebuild. Source: [compose.example.env:15-30]()

## Troubleshooting

Most reported issues fall into three buckets, each with a deterministic recovery path documented in `docs/troubleshooting.md` and exercised by `scripts/healthcheck.sh`.

- **Install one-liner fails partway**: the v0.6.7 release was specifically the patch that made the curl|bash flow run end-to-end; on older hosts, re-running with `--existing` is safe and idempotent. Source: [docs/troubleshooting.md:1-40](); [scripts/install.sh:1-40]()
- **`.opencode` symlink missing or stale**: deleting the symlink and re-creating it from `~/.neuralgentics/.opencode` resolves persona/skill pickup issues without touching the install. Source: [docs/troubleshooting.md:40-80]()
- **Sidecar not ready**: run `scripts/healthcheck.sh`; if the sidecar handshake fails while Postgres is healthy, the typical cause is an `.env` change that referenced a tool module the sidecar image does not bundle — falling back to the example env and restarting the sidecar alone is the recommended recovery. Source: [scripts/healthcheck.sh:1-50](); [docker/sidecar.Dockerfile:1-30]()

For full removal, `scripts/uninstall.sh` reverses the install (deletes `~/.neuralgentics/`) and leaves the project-local `.opencode` symlink in place so the user can decide whether to remove it. Source: [scripts/uninstall.sh:1-30]()

The sidecar model — separate image, dependency-ordered compose lifecycle, env-driven tool selection, and a dedicated healthcheck — is the contract the project has held stable from v0.6.7 through v0.9.2, which is why the install, activation, and teardown commands have not needed to change across those releases.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Veedubin/neuralgentics

Summary: Found 16 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Neuralgentics v0.6.7
- User impact: Upgrade or migration may change expected behavior: Neuralgentics v0.6.7
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.6.7

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Neuralgentics v0.6.8
- User impact: Upgrade or migration may change expected behavior: Neuralgentics v0.6.8
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.6.8

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Neuralgentics v0.7.0
- User impact: Upgrade or migration may change expected behavior: Neuralgentics v0.7.0
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.0

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Neuralgentics v0.7.1
- User impact: Upgrade or migration may change expected behavior: Neuralgentics v0.7.1
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.1

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: neuralgentics-0.7.2
- User impact: Upgrade or migration may change expected behavior: neuralgentics-0.7.2
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.2

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: neuralgentics-0.7.3
- User impact: Upgrade or migration may change expected behavior: neuralgentics-0.7.3
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.7.3

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: neuralgentics-0.8.0
- User impact: Upgrade or migration may change expected behavior: neuralgentics-0.8.0
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.8.0

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: neuralgentics-0.9.0
- User impact: Upgrade or migration may change expected behavior: neuralgentics-0.9.0
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.0

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: neuralgentics-0.9.1
- User impact: Upgrade or migration may change expected behavior: neuralgentics-0.9.1
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.1

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: neuralgentics-0.9.2
- User impact: Upgrade or migration may change expected behavior: neuralgentics-0.9.2
- Evidence: failure_mode_cluster:github_release | https://github.com/Veedubin/neuralgentics/releases/tag/v0.9.2

## 11. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/Veedubin/neuralgentics

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Veedubin/neuralgentics

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/Veedubin/neuralgentics

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/Veedubin/neuralgentics

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Veedubin/neuralgentics

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Veedubin/neuralgentics

<!-- canonical_name: Veedubin/neuralgentics; human_manual_source: deepwiki_human_wiki -->