go-mivia

# Mivia Current release: `v0.2.3` Local-first context, reliability, and collective-learning platform for AI-agent work.  ## Overview This repository contains the local Mivia service platform. The current service is `mivia-server`, a Go HTTP server that exposes REST APIs under `/api/v1` and MCP Streamable HTTP under `/mcp` for local agent-control, redacted agent-run metadata, promotion-gate decisions, Knowledge Promotion metadata, research metadata, project registry, project ingestion, reliability checks, context packs, workflow TOML validation/import/compile metadata, and semantic code-context workflows. It also provides `mivia-server config check --config <path> --redacted-json` for operator-safe config validation reports. The dashboard includes a persistent, redacted Agent Activity stream so engineers can inspect recent MCP calls, correlate them with agent runs, workspace edits, ingestion runs, verifier attempts, failures, and promotion decisions through `trace_id`/`run_id`, reconnect without losing events, and see normalized policy guard events without persisting raw payloads by default. The platform is local-first and localhost-only by default. It stores local metadata through the Ladybug graph abstraction and SQLite app-configuration store, supports optional local project configuration, and can run manual metadata-only project digests plus explicitly opted-in local content graph ingestion with governed FTS, named AST search, git status/diff, eligible file create/delete, and exact token-guarded file edits. It also supports approved local Jira/Confluence project integrations with polling-only ingestion and bounded local graph search/read. It does not call live AI or browsing providers, expose public APIs, run embeddings/vector storage, crawl arbitrary roots, expose arbitrary shell, or use production database infrastructure. Canonical workflow rules live in `.ai/`. Root agent files are thin adapters only.    ## Feature Map ```mermaid flowchart TB Client["Local engineer, Codex Desktop, or MCP client"] Server["mivia-server localhost"] REST["REST /api/v1"] MCP["MCP /mcp"] Tasks["Tasks and research metadata"] WorkPlans["Work Plans: persistent execution structure"] WorkTasks["Work Tasks: isolated-worker-ready units"] Workflows["Workflow TOML: validate, import, compile metadata"] PermissionSnapshots["Permission snapshots: immutable workflow policy metadata"] ReviewGate["Independent review gate"] VerifierGate["Orchestrator verifier gate"] AgentRuns["Redacted agent-run metadata"] Activity["Agent Activity: trace_id/run_id SSE, reconnect replay, policy events"] Registry["Local project registry"] Reliability["Reliability checks: context health, impact analysis, stale claims"] ContextPack["Context packs: search hits, files, symbols, impact, manifests"] Evidence["Evidence Graph: claims, evidence, decisions, actions, outcomes"] Confidence["Confidence Engine: claim scores and recommendations"] Promotion["Promotion gates: candidate, validated, promoted, rejected"] Knowledge["Knowledge Promotion: project default, optional org, reuse events"] Automation["Project automation: Codex CLI over ready Work Tasks"] Digest["Metadata-only digest"] Scheduler["Fair ingestion scheduler"] Live["Live watcher and rescan queue"] Workers["Parallel full-scan file workers"] Flush["Weighted prepared-file flush windows"] Safety["Safety gates: path, symlink, include/exclude, size, binary, UTF-8, sensitive markers"] Extractors["Extractors: Go AST, Tree-sitter JS/TS/TSX/C#/Python/Dart, Markdown, infra/config"] Router["Project graph router"] Graph["Per-project Ladybug graph: files, chunks, symbols, references, calls, headings"] SQLite["SQLite: config, run state, file state, extractor cache"] FTS["Per-project SQLite FTS5: eligible indexed search rows"] AST["Named AST search catalog"] Queries["Bounded query APIs: files, chunks, outlines, FTS search, symbol source, refs, callers, callees, call graph, AST search"] Workspace["Workspace APIs: governed git status/diff, file read/create/delete, token-guarded exact edit"] GitOps["Runner GitOps: commit, push, draft PR refs"] Integrations["Project integrations: Jira and Confluence polling, local rich-content graph search/read"] Boundaries["No public exposure, auth changes, AI provider calls, crawling, embeddings, raw DB queries, arbitrary shell, raw patches, direct MCP git write tools, secrets, roots, prompts, or skipped sensitive content"] Client --> Server Server --> REST Server --> MCP REST --> Tasks MCP --> Tasks REST --> WorkPlans MCP --> WorkPlans REST --> Workflows MCP --> Workflows Workflows --> WorkPlans Workflows --> WorkTasks Workflows --> ReviewGate Workflows --> PermissionSnapshots PermissionSnapshots --> Automation WorkPlans --> WorkTasks WorkTasks --> ContextPack WorkTasks --> Evidence WorkTasks --> ReviewGate WorkTasks --> VerifierGate ReviewGate --> WorkTasks VerifierGate --> WorkTasks WorkTasks --> Confidence WorkTasks --> Promotion WorkTasks --> Knowledge REST --> Automation MCP --> Automation Automation --> WorkTasks Automation --> GitOps Automation --> ReviewGate Automation --> VerifierGate GitOps --> VerifierGate REST --> AgentRuns MCP --> AgentRuns REST --> Activity MCP --> Activity AgentRuns --> Promotion AgentRuns --> Knowledge REST --> Registry MCP --> Registry REST --> Reliability MCP --> Reliability REST --> ContextPack MCP --> ContextPack Registry --> Digest Reliability --> Registry Reliability --> Workspace Reliability --> Queries Registry --> Scheduler Live --> Scheduler Scheduler --> Workers Workers --> Safety Safety --> Extractors Extractors --> Flush Flush --> Router Router --> Graph Extractors --> SQLite Flush --> FTS Extractors --> AST Graph --> Queries SQLite --> Queries FTS --> Queries AST --> Queries Registry --> Workspace Safety --> Workspace GitOps --> Boundaries Queries --> REST Queries --> MCP Queries --> ContextPack Reliability --> ContextPack Evidence --> Confidence Confidence --> Knowledge Promotion --> Knowledge ContextPack --> REST ContextPack --> MCP Workspace --> REST Workspace --> MCP Registry --> Integrations Integrations --> Graph Integrations --> SQLite Integrations --> MCP AgentRuns --> Graph Knowledge --> Graph AgentRuns --> SQLite Server --> Boundaries Safety --> Boundaries ``` | Area | What exists now | Guardrails | | --- | --- | --- | | Local control surface | Health checks, REST `/api/v1`, MCP Streamable HTTP `/mcp` | Localhost-only default; no public/auth production posture | | Config validation | `mivia-server config check --config <path> --redacted-json` writes a machine-readable support report for config, project, ingestion, and workspace validation | Redacts local roots, bind/URL values, config paths, Cloud IDs, and credential references; reports classes/counts/categories only | | Tasks, research, and agent-run metadata | Local task records, research-run/source metadata, redacted agent-run execution metadata | No raw prompts, completions, source dumps, raw stderr, provider payloads, raw fetched content, secrets, roots, or PII | | Workflow TOML | Validation, import, lifecycle metadata, agent definitions with bounded instructions, permission snapshots, and compile-to-Work-Plan refs | Compile-only; TOML never executes directly, import does not run automation, agent instructions are operational metadata rather than raw prompts, and Work Plan/Work Task governance remains mandatory | | Work Plans and Work Tasks | Governed workflow contract for multi-step work that links context health, context pack refs, Evidence Graph refs, Confidence Engine assessments, independent review refs, verifier result refs, Agent Activity, AgentRun refs, and Knowledge Promotion candidate refs. Work Task create metadata includes explicit `files_to_read`, `files_to_edit`, `likely_files_affected`, `review_gate`, `status`, and `decomposition_quality` fields so low-intelligence workers get complete task packets without path-like prose hacks. | Completion requires verifier refs plus independent review refs or a bounded tiny-task review exemption; verify the running REST/MCP surface before calling routes/tools; metadata-only and no raw prompts, completions, source dumps, raw stderr, provider payloads, secrets, roots, external URLs, or PII | | Project automation | Metadata-only automation definitions and runs over Work Plans and ready Work Tasks, with Codex CLI required when available. When `automation.work_plan_status_trigger` is enabled, a Work Plan entering a configured status such as `active` queues each enabled automatic automation for that plan once; executor polling does not create automatic runs by itself. Confirmed review findings can create remediation Work Plans, ready Work Tasks, and enabled automatic implementation automations through the dedicated confirmed-finding tool. Managed mode lets `mivia-server` own execution in native runtimes; Docker Compose and devcontainer configs use external mode with a `mivia-automation-runner` sidecar; external mode also supports any explicitly supervised runner. Successful external-runner Codex execution can run configured GitOps before verifier-required state: commit task changes, optionally push the task branch, and optionally create/update a draft PR. The orchestrator still attaches independent review/verifier refs and completes tasks. | Disabled for execution by default; GitOps is disabled by default and uses fixed git/gh command templates only; no arbitrary shell, no silent manual fallback, no raw prompts, completions, source dumps, raw stderr, provider payloads, secrets, roots, external URLs, or PII | | Independent review capacity | Review gates compile into reviewer Work Tasks and can be executed by Mivia automation or an already independent reviewer run. Codex Desktop subagents are optional client helpers, not the capacity source of truth. | If a client cannot spawn a new thread, queue/claim the reviewer Work Task or block with `reviewer_capacity_unavailable`; never self-review or bypass review | | Promotion gates | Metadata-only artifact promotion decisions with `candidate`, `validated`, `promoted`, and `rejected` states | Existing artifact refs only; refs and decisions stay bounded and redacted | | Knowledge Promotion | Project-level reusable knowledge by default, optional stricter org-level knowledge, supersession, and reuse events | Promoted knowledge is guidance, not proof; agents revalidate before acting and never store raw prompts, completions, source dumps, raw stderr, provider payloads, secrets, roots, external URLs, or PII | | Project registry | Optional local TOML projects with metadata-only digest or content graph mode | Root paths and local config values stay out of REST/MCP responses | | Reliability checks | Context health, changed-path impact analysis, and deterministic stale-claim checking | Metadata-only; no verifier recommendation, eval runner, LLM judgment, raw diff echoing, broad crawling, or `.ai/tasks/*` stable-doc links | | Context packs | Bounded package of search snippets, indexed file metadata, symbol metadata, optional impact analysis, and manifest-only reproducibility metadata | No new storage, provider calls, roots, raw diffs, full chunk text, or full source by default | | Ingestion scheduler | Async manual ingestion, live watcher rescan, configurable global/per-project limits, live path priority | Global limits cap full-scan file workers; operators can cap workers per project when fairness matters | | Full-scan ingestion | Parallel bounded file workers, weighted prepared-file storage flushes, periodic running counters, stale cleanup after workers drain | Source is stored only for eligible chunks after safety gates; heavy graph/search write units flush before the file-count cap | | Semantic graph | Files, chunks, headings, symbols, references, direct calls, callers/callees, bounded call graph, named AST structural search, AST query catalog discovery | No embeddings, vectors, crawling, provider calls, or raw DB query endpoint | | Search index | Per-project SQLite FTS5 rows for eligible chunks, files, symbols, references, and calls; async rebuild repair through ingestion scheduler | Raw FTS syntax and raw SQLite errors are never exposed | | Query APIs | Files, chunks, outlines, text/file/symbol/reference/call search, AST query catalog, named AST search, symbols, symbol source, references, callers, callees, call graph | Explicit pagination and source caps; skipped sensitive content is not returned; raw FTS and raw Tree-sitter syntax are not exposed | | Workspace APIs | Governed git status/diff, current eligible file read, new eligible text-file create, eligible single-file delete, token-guarded exact byte-span edits | Disabled by default; requires global workspace gate plus per-project `workspace_mode`; no arbitrary shell, raw patch, recursive delete, or direct MCP git commit/push/reset/checkout tools | | Project integrations | Jira/Confluence configured provider status, manual/scheduled polling, local rich-content graph search/read | Atlassian Cloud only; polling-only; env/file credential refs; explicit project/space allowlists; rich content stays in ignored local stores | | Dashboard agent activity | Project details `Agent activity` drawer streams persisted redacted recent events, live MCP calls, agent-run lifecycle events, verifier metadata, promotion decisions, and normalized policy guard events over SSE with reconnect cursor replay, `trace_id`/`run_id`, method/tool/status/duration, failure category, policy category, client class, and input/output summary classes | Localhost debug surface only; policy events store categories and safe relative paths only; live raw payloads may contain source, prompts, secrets, or personal data, and persistent raw payload/hash retention requires explicit debug opt-in | ## Start Here Use this repo as a local context server for engineers and AI agents: | Need | Use | | --- | --- | | Business overview | Read `Business View` below. | | Engineer setup and smoke tests | [Local development runbook](docs/runbooks/local-dev.md). | | How Serena, MCP, REST, and shell work together | [Agent context server guide](docs/agent-context-guide.md). | | REST contract | [OpenAPI contract](api/openapi/agent-control.v1.yaml). | | MCP contract | [MCP capability contract](api/mcp/agent-control.v1.md). | ## Business View `mivia-server` is a local control, context, and collective-learning service for engineers and AI agents. It gives agents a safe, structured way to understand approved local workspaces, verify claims, promote reusable knowledge, and expose that context through REST and MCP without sending source code to AI providers. ```mermaid flowchart LR Engineer["Engineer"] Agent["AI agent or Codex Desktop"] Server["mivia-server on localhost"] Projects["Local projects"] Atlassian["Configured Jira and Confluence Cloud"] Scheduler["Fair scheduler and live watcher"] Poller["Integration poller"] Safety["Safety gates"] Graph["Local semantic graph"] SQLite["Local run, file, config, and cache state"] APIs["REST and MCP bounded APIs"] Workspace["Governed workspace status/diff/read/edit"] IntegrationTools["Integration MCP tools: status, poll, search, read"] ContextPack["Context pack builder"] Promotion["Promotion gate records"] Evidence["Evidence Graph metadata"] Confidence["Confidence Engine scores"] Knowledge["Knowledge Promotion: project default, explicit org"] Reuse["Reuse events and supersession"] Dashboard["Dashboard: activity and knowledge view"] Engineer --> Agent Agent --> Server Server --> APIs APIs --> Workspace APIs --> IntegrationTools APIs --> ContextPack APIs --> Scheduler APIs --> Evidence APIs --> Confidence APIs --> Knowledge APIs --> Dashboard Scheduler --> Projects Projects --> Safety IntegrationTools --> Poller Poller --> Atlassian Poller --> Graph Poller --> SQLite Safety --> Workspace Safety --> Graph Safety --> SQLite Graph --> APIs SQLite --> APIs Graph --> ContextPack ContextPack --> APIs Workspace --> APIs APIs --> Agent Agent --> Promotion Agent --> Evidence Agent --> Confidence Agent --> Knowledge Agent --> Reuse Promotion --> APIs Evidence --> Knowledge Confidence --> Knowledge Knowledge --> Reuse Reuse --> APIs Dashboard --> Engineer Graph --> Value["Faster, safer codebase understanding"] SQLite --> Value Workspace --> Value IntegrationTools --> Value Knowledge --> Value Value --> Engineer ``` What this enables: - Engineers can opt local projects into metadata-only digest or content graph ingestion. - Engineers can opt project-specific Jira/Confluence allowlists into polling-only ingestion so issue/page context lands in the same local graph as source context. - Operators can run `mivia-server config check --config <path> --redacted-json` to produce a support-bundle-style validation report without exposing local roots, URLs, Cloud IDs, credential refs, or config paths. - Agents can ask for bounded project files, chunks, outlines, search results, symbols, symbol source, references, direct call edges, call graphs, the supported AST query catalog, named AST structural matches, and ingestion status through MCP instead of guessing from stale chat context. - Agents can ask for a context pack that combines bounded search snippets, indexed file metadata, symbol metadata, optional impact analysis, and a manifest-only reproducibility record in one response. - Agents can ask for context health, changed-path impact analysis, and deterministic stale-claim checks against selected stable docs/contracts before relying on local context. - Agents can validate and import workflow TOML only as metadata, then compile enabled workflow metadata into Work Plans, Work Tasks, reviewer tasks, automation definitions, and permission snapshot refs. Workflow TOML is not a runner and does not execute directly. Automation cannot bypass Work Plans/Tasks, required review gates, independent review refs, orchestrator verifier refs, Evidence Graph outcomes, confidence scoring, or Knowledge Promotion gates. - Checked-in workflow definitions include governed decomposition/planning, governed Work Plan implementation, and governed automatic code review bug planning. The code-review workflow can auto-fire through enabled automatic automation metadata: it scans bounded review scope, independently confirms only evidence-backed bugs, deduplicates findings, and creates bug Work Plans only for confirmed defects. It must not auto-implement speculative or unreviewed findings. - Governed multi-step agents must use Work Plans and Work Tasks when the running server exposes them. The required workflow is: verify context health, build/attach context pack refs, decompose into isolated-worker-ready tasks, claim/start one task, attach Evidence Graph or claim refs, attach independent review result refs for non-trivial or write-capable tasks, attach orchestrator verifier result refs, record Agent Activity/AgentRun metadata, use Confidence Engine where claims may become knowledge, and create/link Knowledge Promotion candidates only through the gated flow. Each task must be executable by a low-intelligence worker from task metadata and attached refs alone, without prior chat memory or hidden orchestrator context. Verification must be written for orchestrator-run verification; scoped workers may write tests or artifacts but must not run verifier commands unless explicitly allowed. The implementing run cannot attach its own review result when run IDs are known, and task completion requires verifier refs plus independent review refs or a bounded tiny-task `review_exempt_reason`. Verify route/tool availability against the running server before calling them. - Automation tools, when exposed, execute over Work Plans and ready Work Tasks only. They are not a replacement for Work Plan/Work Task creation, Evidence Graph metadata, Confidence Engine scoring, verifier refs, or Knowledge Promotion gates. With `automation.work_plan_status_trigger.enabled = true`, moving a Work Plan into `active` queues matching enabled automatic automations once; executor polling only executes queued runs and does not create automatic runs from ready tasks. Review gates and dependency checks still decide whether a queued run can execute. Use `projects.automations.create_remediation_from_finding` only for independently confirmed bugs; it creates a remediation Work Plan, ready Work Task, and enabled automatic implementation automation from safe finding metadata. Generated remediation tasks require a focused regression test when feasible, or a concrete not-feasible reason in the task outcome. When `activate_plan=true`, the generated Work Plan status trigger queues remediation automatically; normal operation should not manually call `projects.automations.run`. Use the automation status update surface to pause or disable stale automation metadata without deleting history. Managed automation lets `mivia-server` submit and execute queued runs without a manually started watcher in native Linux, macOS, or WSL runtimes. Docker Compose and devcontainer configs use external mode with the checked-in `mivia-automation-runner` sidecar, which starts with the stack and claims queued `codex_cli` runs. Executable automation must not silently fall back to manual mode. Parallel subagent work must be orchestrator-owned and limited to tasks with proven independent dependencies and disjoint file/verifier/artifact scope. - When `[git_operations]` is enabled for a supervised external runner, the runner performs post-task GitOps only after Codex exits successfully and before reporting the attempt. It inspects the configured `--codex-cd` worktree, commits changed task files with a configurable deterministic Conventional Commit convention, optionally pushes with a configured SSH identity, and optionally creates or updates a draft GitHub PR through `gh` using configured safe templates. Global GitOps config is only the fallback; repository-specific branch, commit, PR title, and PR body rules belong under each project's `[projects.git_operations]` override. Push/PR fails closed when the current branch violates the selected project's `branch_prefix` or `branch_name_pattern`. PR metadata includes project ID, Work Plan ID, Work Task ID, automation ID, automation run ID, operator ID, review refs, verifier refs, and test results when available. Post-task commit fails closed unless the Work Task supplies at least one safe scoped affected path; the runner does not fall back to staging the whole worktree. Public key paths are validation metadata only; push needs a private key and `known_hosts`. GitHub auth must come from an env or file reference, never a token literal in TOML. GitOps refs attached to runs are safe identifiers such as commit, push, and PR refs; no key contents, token values, raw command output, roots, or stderr are stored. - Agents can record redacted run metadata, steps, verifier outcomes, changed file paths, and artifact refs without storing raw prompts, completions, source dumps, raw stderr, secrets, roots, provider payloads, or PII. - Agents can record Evidence Graph metadata, score confidence, and promote only verified conclusions into reusable knowledge. - Agents must query project-level promoted knowledge before planning, query org-level promoted knowledge before cross-project claims, revalidate promoted knowledge before acting, and record reuse events. Project-level promotion is the default. Org-level promotion is optional, stricter, explicit, and never automatic. Stale or contradicted knowledge is superseded, not deleted. - Agents can ask local MCP tools for configured integration status, trigger a one-shot provider poll, search locally ingested Jira/Confluence chunks, and read bounded Jira issue or Confluence page content without calling Atlassian during search/read. - Agents can use MCP/REST for governed git status/diff, current eligible file reads, exact token-guarded edits, eligible single-file deletes, and new eligible text-file creates on opted-in workspaces; for `workspace_mode = "edit"`, use workspace `file_read` then `file_edit`/`file_delete` for existing files, and `file_create` for new eligible text files before shell, `apply_patch`, or manual file operations. Read maxes are caps that may truncate responses, not a fallback trigger by themselves. These workspace tools do not provide recursive delete, arbitrary patch upload, arbitrary shell, or a shell replacement. Shell remains required for tests, builds, logs, process control, arbitrary commands, generated-file verification, and non-opted-in repositories. - Engineers can open the dashboard to inspect agent activity and Knowledge Promotion state, including project and org scope separation, reuse events, and explicit org promotion review. Agent activity still shows project-scoped MCP calls, agent-run trace events, verifier metadata, promotion decisions, and policy guard events in real time. - Full scans run asynchronously through a fair scheduler, use bounded per-project file workers, and persist running progress counters during long scans. - Local graph/search state persists per project when `graph_storage = "persistent"` using `<ladybug_path parent>/projects/<project-id>/mivialabs.lbug` and `<ladybug_path parent>/projects/<project-id>/mivialabs-pebble-search.sqlite`, or stays process-local/shared fallback with `graph_storage = "in_memory"`. - Mivia keeps `full_scan_batch_size` as a hard file-count cap and also flushes earlier by graph/search write weight so heavy files do not create multi-minute per-project storage writes. - The server keeps the boundary localhost-only and blocks raw DB queries, public exposure, AI provider calls, embeddings, vectors, arbitrary shell, raw patches, git commit/push/reset/checkout tools, skipped sensitive content, secrets, raw prompts, raw completions, raw source dumps, raw stderr, roots, external URLs, PII, and raw provider payload blobs. Approved Jira/Confluence rich content and possible PII are limited to ignored local stores and bounded local MCP responses. ## Agent Reliability Model `mivia-server`, Serena, and shell solve different parts of reliable agent work: - `mivia-server` is first choice for indexed project discovery, ingestion freshness, promoted knowledge, Evidence Graph metadata, Confidence Engine scoring, files, chunks, symbols, references, calls, FTS search, symbol source, call graph, named AST search, and locally ingested Jira/Confluence context. - Serena remains useful when MCP is unavailable, stale, missing the project, or lacks the edit-time semantic operation needed for a precise code change. - MCP can handle governed git status/diff and current eligible file reads for `read_only` or `edit` workspaces, plus exact token-guarded edits, eligible single-file deletes, and new eligible text-file creates for `edit` workspaces. Prefer workspace file read/edit/delete for existing eligible files and file_create for new eligible text files before shell, `apply_patch`, or manual file operations when eligible; shell remains the source of truth for tests, builds, logs, process control, generated files, arbitrary commands, and non-opted-in repositories. - Agents must query `projects.knowledge.list` before planning in the current workspace and `orgs.knowledge.list` before cross-workspace claims, then revalidate before acting and record reuse with `projects.knowledge.reuse_events.record`. - This routing reduces blind file scanning, stale assumptions, and unsafe over-broad context collection. ```mermaid flowchart TB Agent["AI agent"] MCP["mivia-server MCP first for indexed context and opted-in workspace"] Serena["Serena fallback or edit-time semantic tools"] Shell["Shell for tests, builds, logs, process control, generated files, arbitrary commands, and non-opted-in repos"] Source["Source files"] Workspace["Governed workspace status/diff/read/create/delete/edit"] Integrations["Local Jira/Confluence status, polling, graph search/read"] Knowledge["Promoted knowledge lookup"] Evidence["Evidence Graph"] Confidence["Confidence Engine"] Reuse["Reuse event or supersession"] Indexed["Files, chunks, symbols, refs, calls, AST matches"] IntegrationContext["Issue/page artifacts and chunks"] Registry["Project registry and ingestion status"] Ingestion["Live and manual content graph ingestion"] Polling["Polling-only integration ingestion"] Store["Project-scoped graph/search stores plus SQLite state"] Guardrails["Safety gates and policy boundaries"] Agent --> MCP MCP --> Registry MCP --> Ingestion MCP --> Workspace MCP --> Integrations MCP --> Knowledge MCP --> Evidence MCP --> Confidence Ingestion --> Guardrails Integrations --> Polling Polling --> Guardrails Workspace --> Guardrails Guardrails --> Store Store --> Indexed Store --> IntegrationContext Store --> Knowledge Indexed --> MCP IntegrationContext --> MCP Knowledge --> MCP Store --> MCP Agent --> Serena Serena --> Source Agent --> Shell Shell --> Source Decision --> Reuse Reuse --> MCP MCP --> Decision["Grounded implementation decisions"] Serena --> Decision Shell --> Decision Decision --> Agent ``` High-level flow: ```mermaid sequenceDiagram participant Engineer participant Agent participant Server as mivia-server participant Serena participant Shell participant Project as Local project participant Atlassian as Jira/Confluence Cloud participant Evidence as Evidence Graph participant Confidence as Confidence Engine participant Knowledge as Knowledge Promotion participant Store as Local graph, SQLite, and FTS Engineer->>Agent: Ask for implementation or review Agent->>Server: Query promoted project knowledge before planning Agent->>Server: Query org knowledge before cross-workspace claims Agent->>Server: Query metadata, ingestion state, search, symbols, refs, calls, AST, bounded chunks, integration context, and workspace status/diff/read/edit Server->>Project: Read only eligible local files after safety gates Server->>Store: Persist approved local metadata and graph context Server->>Atlassian: Poll configured project/space allowlists only when manually or locally scheduled Server->>Store: Persist approved integration metadata and bounded rich-content chunks Store-->>Server: Return bounded context Server-->>Agent: Return governed project context Agent->>Serena: Fall back for edit-time semantic gaps Serena-->>Agent: Return precise code structure when needed Agent->>Shell: Verify tests, build, logs, process control, generated files, and non-opted-in repo state Shell-->>Agent: Return runtime evidence Agent->>Evidence: Record safe claim, evidence, decision, action, and outcome refs Agent->>Confidence: Score confidence from safe metadata Agent->>Knowledge: Promote project knowledge only after gates pass Agent->>Knowledge: Record used, skipped, stale, or contradicted reuse Agent-->>Engineer: Make a smaller, verified change with clearer evidence ``` ## Baseline - Module: `github.com/MiviaLabs/go-mivia` - Go: `1.26` - Toolchain: `go1.26.3` - Module strategy: one root `go.mod`; add `go.work` only if independent module release boundaries become real. - Server: `cmd/mivia-server` - Local project config: optional, local-only TOML loaded from `configs/mivia-server.local.toml` or explicit `MIVIA_CONFIG_PATH`; committed example is `configs/mivia-server.example.toml`. - Persistence: LadybugDB graph abstraction for graph data; SQLite via `modernc.org/sqlite` for local app configuration and FTS search. Project graph/search storage is selectable per project with `graph_storage = "persistent"` or `graph_storage = "in_memory"`; persistent project stores derive from `storage.ladybug_path` as `<parent>/projects/<project-id>/mivialabs.lbug` and `<parent>/projects/<project-id>/mivialabs-pebble-search.sqlite`. Ingestion writes are routed to the target project backend and flushed in bounded prepared-file windows by file count and write weight. - Interfaces: REST under `/api/v1`; MCP Streamable HTTP under `/mcp`. ## Layout - `.ai/`: canonical agent workflow rules, skills, and handoffs. Local task and research plans are ignored working artifacts, not technical docs. - `api/openapi/`: REST OpenAPI contracts. - `api/mcp/`: MCP capability docs. - `cmd/mivia-server/`: Mivia server entrypoint. - `configs/`: committed local config examples only; developer-local configs stay ignored. - `internal/agentcontrol/`: task and research-run domain, stores, REST adapter, MCP adapter. - `internal/projectregistry/`: local project config registry, validation, REST/MCP metadata APIs, and manual metadata-only digest. - `internal/projectworkspace/`: governed local workspace git status/diff, file read/create/delete, and exact edit domain. - `internal/research/`: fixture-only research boundaries, redaction, metadata storage, REST/MCP hooks. - `internal/platform/`: config, logging, health, HTTP, Ladybug, SQLite platform packages. - `docs/`: stable technical documentation index. - `docs/architecture/`: system architecture and data-flow docs. - `docs/adr/`: architecture decision records. - `docs/configuration/`: local configuration guides. - `docs/research/`: source-grounded baseline notes only; do not store or link research plans. - `docs/runbooks/`: local development and incident runbooks. - `docs/security/`: privacy and research-data handling baselines. - `db/migrations/`: unused during the LadybugDB bootstrap; schema bootstrap belongs behind internal store code until an ADR changes this. - `tools/`: build-tagged dependency anchors; not application code. ## Documentation - [Documentation index](docs/README.md) - [Agent context server guide](docs/agent-context-guide.md) - [System architecture](docs/architecture/system-architecture.md) - [REST OpenAPI contract](api/openapi/agent-control.v1.yaml) - [MCP capability contract](api/mcp/agent-control.v1.md) - [Local project configuration](docs/configuration/local-projects.md) - [Local development runbook](docs/runbooks/local-dev.md) - [Privacy baseline](docs/security/privacy-baseline.md) - [Research data handling](docs/security/research-data-handling.md) Do not link `.ai/tasks/*` files or research-plan files from technical docs. They are local, stale-prone working artifacts. ## Local Checks ```sh go version go mod tidy go test ./... make check ``` If `go` is missing, install Go 1.26.x before treating verification as complete. ## Run Locally Foreground server: ```sh MIVIA_HTTP_ADDR=127.0.0.1:8080 \ MIVIA_SQLITE_PATH=:memory: \ go run ./cmd/mivia-server ``` Optional local project config: ```sh cp configs/mivia-server.example.toml configs/mivia-server.local.toml MIVIA_CONFIG_PATH=configs/mivia-server.local.toml go run ./cmd/mivia-server ``` Use placeholder paths only in committed docs and examples. Local configs are ignored and must not contain secrets, tokens, PII, raw prompts, raw source content, or provider payloads. Smoke: ```sh curl -fsS http://127.0.0.1:8080/healthz curl -fsS http://127.0.0.1:8080/readyz curl -fsS -H 'Content-Type: application/json' \ -d '{"title":"local smoke"}' \ http://127.0.0.1:8080/api/v1/tasks curl -fsS http://127.0.0.1:8080/api/v1/projects curl -fsS \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-06-18' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \ http://127.0.0.1:8080/mcp ``` Docker Compose, without requiring Go on the host: ```sh docker compose up ``` The Compose service publishes to `${MIVIA_HOST_BIND:-127.0.0.1}:${MIVIA_HOST_PORT:-8080}`. Keep `MIVIA_HOST_BIND=127.0.0.1` unless an approved local-only network exposure requires otherwise. Inside the container, `mivia-server` still binds to `127.0.0.1:18080`; a local TCP forwarder exposes container port `8080` so Docker port publishing works without relaxing the server's localhost-only bind rule. Default container data paths are: ```sh MIVIA_LADYBUG_PATH=/var/lib/mivia/mivialabs.lbug MIVIA_SQLITE_PATH=/var/lib/mivia/mivialabs-config.sqlite ``` Persistent project graph/search files live under `/var/lib/mivia/projects/<project-id>/`; agent and research metadata remain separate from project graph storage. Mivia bounds heavy per-project graph/search flushes during ingestion; tune `full_scan_batch_size` in the mounted TOML as the hard file-count cap if a local disk still needs smaller write units. Override `MIVIA_HOST_BIND`, `MIVIA_HOST_PORT`, and feature flags from the host environment when needed. Compose loads `configs/mivia-server.compose.toml`, which mirrors the local global runtime defaults without project roots, project names, Jira/Confluence URLs, or credential refs. It enables content graph ingestion, live updates, diagnostics, runtime metrics, and the global workspace gate by default. Per-project `workspace_mode` still controls whether a configured project exposes workspace tools. Mount ignored local configs or secrets only in an ignored `.docker-compose.local.yml` override when needed. The image defaults to `MIVIA_CONTAINER_USER=10001:10001`. For local automation over bind-mounted checkouts, prefer `scripts/mivia-compose-up -d`; it infers `MIVIA_AUTOMATION_UID` and `MIVIA_AUTOMATION_GID` from `id -u` and `id -g` so automation commits, refs, and worktree metadata stay owned by the checkout user. Configure `MIVIA_CONTAINER_USER` separately for the server data volume and workspace mounts. Avoid root-run automation except for one-time ownership repair. To run with an ignored local config and local credential file: ```sh docker compose -f docker-compose.yml -f .docker-compose.local.yml up ``` ## Codex Desktop MCP Codex Desktop can register the server directly as a Streamable HTTP MCP server: ```powershell codex mcp add mivia-server --url http://127.0.0.1:8080/mcp codex mcp get mivia-server ``` For a long-running WSL process from Windows, build once and run the binary: ```powershell wsl -d Ubuntu --cd <repo-root> env PATH=<go-bin-path>:$PATH go build -o <ignored-runtime-dir>/mivia-server ./cmd/mivia-server wsl -d Ubuntu --cd <repo-root> env MIVIA_HTTP_ADDR=127.0.0.1:8080 MIVIA_SQLITE_PATH=:memory: <ignored-runtime-dir>/mivia-server ``` The currently exposed MCP tools are `tasks.create`, `tasks.get`, `research_runs.create`, `research_runs.get`, `research_sources.create`, `research_sources.get`, `agent_runs.create`, `agent_runs.step_append`, `agent_runs.promote_artifact`, `agent_runs.complete`, `agent_runs.get`, `projects.list`, `projects.get`, `projects.digest`, `projects.context_health`, `projects.impact.analyze`, `projects.context_pack.build`, `projects.claims.check`, `projects.evidence_graph.claims.create`, `projects.evidence_graph.claims.get`, `projects.evidence_graph.claims.list`, `projects.evidence_graph.evidence.append`, `projects.evidence_graph.decisions.create`, `projects.evidence_graph.actions.create`, `projects.evidence_graph.outcomes.create`, `projects.evidence_graph.artifacts.link`, `projects.evidence_graph.promotions.link`, `projects.confidence.claims.score`, `projects.confidence.claims.get`, `projects.confidence.claims.list`, `projects.knowledge.candidates.create`, `projects.knowledge.validate`, `projects.knowledge.promote_project`, `projects.knowledge.submit_org_review`, `projects.knowledge.promote_org`, `projects.knowledge.reject`, `projects.knowledge.supersede`, `projects.knowledge.reuse_events.record`, `projects.knowledge.get`, `projects.knowledge.list`, `orgs.knowledge.list`, `projects.workflows.validate_toml`, `projects.workflows.import_toml`, `projects.workflows.get`, `projects.workflows.list`, `projects.workflows.update_status`, `projects.workflows.compile_to_work_plan`, `projects.agent_definitions.list`, `projects.agent_definitions.get`, `projects.permission_snapshots.get`, `projects.permission_snapshots.list`, `projects.work_plans.create`, `projects.work_plans.get`, `projects.work_plans.list`, `projects.work_plans.update_status`, `projects.work_plans.resume`, `projects.work_tasks.create`, `projects.work_tasks.get`, `projects.work_tasks.update_status`, `projects.work_tasks.claim`, `projects.work_tasks.release`, `projects.work_tasks.start`, `projects.work_tasks.complete`, `projects.work_tasks.fail`, `projects.work_tasks.block`, `projects.work_tasks.list_open`, `projects.work_tasks.list_mine`, `projects.work_tasks.list_blocked`, `projects.work_tasks.get_next`, `projects.work_tasks.attach_evidence`, `projects.work_tasks.attach_context_pack`, `projects.work_tasks.attach_claim`, `projects.work_tasks.attach_verifier_result`, `projects.work_tasks.attach_review_result`, `projects.work_tasks.promote_knowledge_candidate`, `projects.automations.create`, `projects.automations.get`, `projects.automations.list`, `projects.automations.update_status`, `projects.automations.run`, `projects.automations.run_parallel_batch`, `projects.automation_runs.get`, `projects.automation_runs.list`, `projects.automation_runs.claim_next`, `projects.automation_runs.complete_attempt`, `projects.ingest`, `projects.search_index.rebuild`, `projects.ingestion_status`, `projects.ingestion_status_latest`, `projects.files.list`, `projects.files.get`, `projects.file.chunks`, `projects.symbols.list`, `projects.search.text`, `projects.search.files`, `projects.search.symbols`, `projects.search.references`, `projects.search.calls`, `projects.search.ast.queries`, `projects.search.ast`, `projects.symbol.source`, `projects.symbol.references`, `projects.symbol.callers`, `projects.symbol.callees`, `projects.symbol.call_graph`, `projects.headings.list`, `projects.file.outline`, `projects.workspace.git_status`, `projects.workspace.git_diff`, `projects.workspace.file_read`, `projects.workspace.file_edit`, `projects.workspace.file_create`, `projects.workspace.file_delete`, `projects.integrations.list`, `projects.integrations.status`, `projects.integrations.counts`, `projects.integrations.poll`, `projects.integrations.poll_status`, `projects.integrations.search`, `projects.jira.issue.get`, and `projects.confluence.page.get`. Codex Desktop may show underscore-normalized callable names such as `tasks_create`, `projects_search_text`, `projects_workspace_file_read`, `projects_workspace_file_edit`, `projects_workspace_file_create`, `projects_workspace_file_delete`, `projects_workflows_validate_toml`, `projects_work_tasks_attach_review_result`, `projects_knowledge_list`, `orgs_knowledge_list`, `projects_automation_runs_claim_next`, or `projects_automations_create`; the server accepts both forms. ## Local Project APIs Project APIs are for engineer local computers only. REST exposes project list/get, manual digest, manual ingestion, ingestion status, file, chunk, and symbol metadata endpoints under `/api/v1`; MCP exposes matching project tools and resources. Use REST for scripts, smoke tests, and direct local checks. Use MCP first when an agent client needs indexed project context or opted-in workspace status/diff/read/create/delete/edit. For `workspace_mode = "edit"`, use MCP workspace `file_read` then `file_edit`/`file_delete` for existing eligible files, and `file_create` for new eligible text files before shell, `apply_patch`, or manual file operations. Use Serena only for edit-time semantic gaps that MCP cannot answer, and use shell for tests, builds, logs, process control, generated-file verification, arbitrary commands, and non-opted-in repos. | Capability | REST | MCP | | --- | --- | --- | | Projects | `GET /api/v1/projects`, `GET /api/v1/projects/{id}` | `projects.list`, `projects.get` | | Metadata digest | `POST /api/v1/projects/{id}/digest-runs` | `projects.digest` | | Context health | `GET /api/v1/projects/{id}/context-health` | `projects.context_health` | | Changed-path impact analysis | `POST /api/v1/projects/{id}/impact/analyze` | `projects.impact.analyze` | | Context pack | `POST /api/v1/projects/{id}/context-pack` | `projects.context_pack.build` | | Stale-claim check | `POST /api/v1/projects/{id}/claims/check` | `projects.claims.check` | | Create knowledge candidate | `POST /api/v1/projects/{id}/knowledge/candidates` | `projects.knowledge.candidates.create` | | Validate knowledge candidate | `POST /api/v1/projects/{id}/knowledge/{knowledge_id}/validate` | `projects.knowledge.validate` | | Promote project knowledge | `POST /api/v1/projects/{id}/knowledge/{knowledge_id}/promote-project` | `projects.knowledge.promote_project` | | Submit knowledge for org review | `POST /api/v1/projects/{id}/knowledge/{knowledge_id}/submit-org-review` | `projects.knowledge.submit_org_review` | | Promote org knowledge | `POST /api/v1/projects/{id}/knowledge/{knowledge_id}/promote-org` | `projects.knowledge.promote_org` | | Reject knowledge | `POST /api/v1/projects/{id}/knowledge/{knowledge_id}/reject` | `projects.knowledge.reject` | | Supersede knowledge | `POST /api/v1/projects/{id}/knowledge/{knowledge_id}/supersede` | `projects.knowledge.supersede` | | Record knowledge reuse event | `POST /api/v1/projects/{id}/knowledge/{knowledge_id}/reuse-events` | `projects.knowledge.reuse_events.record` | | Get project knowledge | `GET /api/v1/projects/{id}/knowledge/{knowledge_id}` | `projects.knowledge.get` | | List project knowledge | `GET /api/v1/projects/{id}/knowledge?scope=&state=&claim_id=&knowledge_ref=&confidence_band=&min_confidence=&max_confidence=&page_size=&page_token=` | `projects.knowledge.list` | | List org knowledge | `GET /api/v1/orgs/{org_ref}/knowledge?state=org_promoted&claim_id=&knowledge_ref=&confidence_band=&min_confidence=&max_confidence=&page_size=&page_token=` | `orgs.knowledge.list` | | Validate workflow TOML | `POST /api/v1/projects/{id}/workflows/validate-toml` | `projects.workflows.validate_toml` | | Import workflow TOML metadata | `POST /api/v1/projects/{id}/workflows/import-toml` | `projects.workflows.import_toml` | | List/get/update workflows | `GET /api/v1/projects/{id}/workflows`, `GET /api/v1/projects/{id}/workflows/{workflow_id}`, `POST /api/v1/projects/{id}/workflows/{workflow_id}/status` | `projects.workflows.list`, `projects.workflows.get`, `projects.workflows.update_status` | | Compile workflow to Work Plan | `POST /api/v1/projects/{id}/workflows/{workflow_id}/compile` | `projects.workflows.compile_to_work_plan` | | Workflow agent definitions | `GET /api/v1/projects/{id}/workflows/{workflow_id}/agent-definitions`, `GET /api/v1/projects/{id}/workflows/{workflow_id}/agent-definitions/{agent_id}` | `projects.agent_definitions.list`, `projects.agent_definitions.get` | | Permission snapshots | `GET /api/v1/projects/{id}/permission-snapshots`, `GET /api/v1/projects/{id}/permission-snapshots/{snapshot_id}` | `projects.permission_snapshots.list`, `projects.permission_snapshots.get` | | Create/list automation | `POST /api/v1/projects/{id}/automations`, `GET /api/v1/projects/{id}/automations` | `projects.automations.create`, `projects.automations.list` | | Update automation status | `POST /api/v1/projects/{id}/automations/{automation_id}/status` | `projects.automations.update_status` | | Execute automation run | `POST /api/v1/projects/{id}/automations/{automation_id}/runs` | `projects.automations.run` | | Plan parallel automation batch | `POST /api/v1/projects/{id}/automations/{automation_id}/parallel-batches` | `projects.automations.run_parallel_batch` | | Read automation runs | `GET /api/v1/projects/{id}/automation-runs`, `GET /api/v1/projects/{id}/automation-runs/{run_id}` | `projects.automation_runs.list`, `projects.automation_runs.get` | | External automation runner | `POST /api/v1/projects/{id}/automation-runs/claim-next`, `POST /api/v1/projects/{id}/automation-runs/{run_id}/attempt-result` | `projects.automation_runs.claim_next`, `projects.automation_runs.complete_attempt` | | Content graph ingestion | `POST /api/v1/projects/{id}/ingestion-runs` | `projects.ingest` | | Search index repair | `POST /api/v1/projects/{id}/search-index/rebuild` | `projects.search_index.rebuild` | | Ingestion run status | `GET /api/v1/projects/{id}/ingestion-runs/{run_id}` | `projects.ingestion_status` | | Latest ingestion status | `GET /api/v1/projects/{id}/ingestion-runs/latest` | `projects.ingestion_status_latest` | | Indexed files | `GET /api/v1/projects/{id}/files?status=eligible&extension=.go` | `projects.files.list` | | Bounded chunks | `GET /api/v1/projects/{id}/files/{file_id}/chunks` | `projects.file.chunks` | | Symbols | `GET /api/v1/projects/{id}/symbols` | `projects.symbols.list` | | Text search | `GET /api/v1/projects/{id}/search/text?query=helper` | `projects.search.text` | | File search | `GET /api/v1/projects/{id}/search/files?path_contains=cmd` | `projects.search.files` | | Symbol search | `GET /api/v1/projects/{id}/search/symbols?name_contains=Run` | `projects.search.symbols` | | Reference search | `GET /api/v1/projects/{id}/search/references?target_name_contains=Run` | `projects.search.references` | | Call search | `GET /api/v1/projects/{id}/search/calls?callee_name_contains=Run` | `projects.search.calls` | | AST query catalog | `GET /api/v1/projects/{id}/search/ast/queries` | `projects.search.ast.queries` | | Named AST search | `GET /api/v1/projects/{id}/search/ast?language=typescript&query=call_expressions` | `projects.search.ast` | | Symbol source | `GET /api/v1/projects/{id}/symbols/{symbol_id}/source` | `projects.symbol.source` | | Symbol references | `GET /api/v1/projects/{id}/symbols/{symbol_id}/references` | `projects.symbol.references` | | Symbol callers | `GET /api/v1/projects/{id}/symbols/{symbol_id}/callers` | `projects.symbol.callers` | | Symbol callees | `GET /api/v1/projects/{id}/symbols/{symbol_id}/callees` | `projects.symbol.callees` | | Symbol call graph | `GET /api/v1/projects/{id}/symbols/{symbol_id}/call-graph` | `projects.symbol.call_graph` | | Governed git status | `GET /api/v1/projects/{id}/workspace/git/status` | `projects.workspace.git_status` | | Governed git diff | `GET /api/v1/projects/{id}/workspace/git/diff` | `projects.workspace.git_diff` | | Current eligible file read | `GET /api/v1/projects/{id}/workspace/files/read` | `projects.workspace.file_read` | | Exact token-guarded file edit | `POST /api/v1/projects/{id}/workspace/files/edit` | `projects.workspace.file_edit` | | New eligible text-file create | `POST /api/v1/projects/{id}/workspace/files/create` | `projects.workspace.file_create` | | Eligible single-file delete | `POST /api/v1/projects/{id}/workspace/files/delete` | `projects.workspace.file_delete` | | Integration providers | Not exposed over REST | `projects.integrations.list` | | Integration status | Not exposed over REST | `projects.integrations.status` | | Local integration counts | Not exposed over REST | `projects.integrations.counts` | | Manual integration poll | Not exposed over REST | `projects.integrations.poll`, then `projects.integrations.poll_status` | | Integration rich-content search | Not exposed over REST | `projects.integrations.search` | | Jira issue local read | Not exposed over REST | `projects.jira.issue.get` | | Confluence page local read | Not exposed over REST | `projects.confluence.page.get` | Manual content graph ingestion and search index repair are asynchronous. `POST /ingestion-runs`, `POST /search-index/rebuild`, `projects.ingest`, and `projects.search_index.rebuild` submit work through the fair scheduler and return queued run metadata quickly; clients poll by `run_id` or check latest status before relying on indexed data. Agents should use indexed search tools first for routine text, path, symbol, reference, and call discovery, and workspace tools first for opted-in git status/diff/current eligible file reads/exact token-guarded edits/eligible file create/delete. Agents should also query `projects.knowledge.list` before planning in the current project, query `orgs.knowledge.list` before cross-project claims, revalidate promoted knowledge before acting, record Evidence Graph metadata and confidence for new conclusions, promote only after gates pass, and record reuse with `projects.knowledge.reuse_events.record`. Treat read maxes as caps that may truncate responses; page, narrow, or re-read through MCP instead of falling back only because a response was capped. Live ingestion is the normal freshness path after workspace edits. Use Serena only for edit-time semantic gaps that MCP cannot answer, and `ast-grep` only for structural search or rewrite work not covered by indexed search. Full task, research, project, REST, and MCP method mapping is in the [agent context server guide](docs/agent-context-guide.md). Project config is local-only and loaded through `MIVIA_CONFIG_PATH` or the ignored default `configs/mivia-server.local.toml`. The committed schema example is [configs/mivia-server.example.toml](configs/mivia-server.example.toml). Project digest is manual and metadata-only. Content graph ingestion is opt-in with `digest_mode = "content_graph"` and uses the same local path, denylist, binary, UTF-8, size, and sensitive-marker gates before storing eligible source chunks. Full-scan storage flushes are bounded by the configured file-count cap and by internal graph/search write weight. Promoted AST extraction uses Go stdlib AST for Go, Tree-sitter for JS/TS/TSX/JSX/C#/Python/Dart, Markdown headings, and lightweight infrastructure metadata. Dart extraction includes generated `.g.dart`, `.freezed.dart`, `.mocks.dart`, and similar files by default unless project include/exclude config filters them. Flutter widget recognition is exposed through symbol/reference/call metadata for widget classes, state classes, build methods, `setState`, `Navigator`, route calls, and widget constructor call candidates. TS/JS/TSX/JSX, C#, Python, and Dart have no regex fallback after startup validation. ### Dart And Flutter Dart projects participate in the same local content graph surfaces as Go, Python, JS/TS, C#, Markdown, and infrastructure files. `.dart` files are chunked, indexed, parsed with Tree-sitter, and exposed through files, symbols, references, calls, outlines, named AST search, and bounded source tools after the normal safety gates pass. Generated Dart files are indexed by default. Do not exclude `.g.dart`, `.freezed.dart`, `.mocks.dart`, `.generated.dart`, or similar files unless a local project explicitly wants less generated-code noise. Flutter support promotes widget classes, state classes, `Widget build(...)` methods, `setState`, `Navigator`, route calls, and widget constructor call candidates as symbol/reference/call metadata. AST catalog entries include Dart `function_declarations`, `class_declarations`, `type_declarations`, `call_expressions`, `imports`, `test_functions`, `assignments`, `error_handling`, `flutter_widgets`, and `flutter_build_methods`. For Flutter navigation, start with `projects.search.ast.queries`, then use `projects.search.ast` with `language=dart&query=flutter_widgets` or `query=flutter_build_methods`. Use `projects.search.symbols` with `kind=flutter_widget`, `kind=flutter_state`, or `kind=flutter_build_method`, and use `projects.search.calls` with `callee_name_contains=Navigator` or `callee_name_contains=setState` when call edges are the useful surface. `projects.search.ast.queries` returns supported named AST query IDs, languages, captures, query versions, matching extensions, and safe per-language `file_too_large` coverage counts so agents can discover the safe structural-search surface before calling `projects.search.ast`. Raw Tree-sitter query syntax remains blocked. Sensitive, denied, absent, parse-error, and other skipped files are not searched. Oversized files are reported as safe coverage gaps through ingestion/file metadata such as `skipped_reason=file_too_large`, size, and reason counts; their source text, chunks, snippets, content hashes, raw parser/SQLite/FTS/Tree-sitter errors, roots, secrets, PII, raw prompts, and provider payloads are not exposed. Extractor cache rows live in the local SQLite app DB and store only serialized symbol, heading, reference, and call metadata keyed by project, relative-path hash, content hash, extractor name, and extractor version. Skipped files do not get cache rows or content hashes. REST/MCP responses omit local root paths, datastore paths, skipped sensitive content, matched sensitive text, secrets, raw prompts, provider payloads, and PII. Symbol source is returned only for eligible indexed chunks and is capped by request and project limits. Live project updates require both global live enablement and per-project `update_policy = "live"`. The watcher is directory-based, non-recursive at the OS API level, and registers each eligible directory; overflow or full queues trigger a scheduled bounded project rescan. Manual and live full scans run through the fair scheduler. Live path events have priority over full-scan continuations, and operators can cap per-project worker use below the global worker count when fairness across projects matters. File outlines support symbol `kind`, `name_prefix`, symbol pagination, and opt-in bounded chunk text for eligible files. Project integrations are configured per project under the Jira and Confluence integration settings. They require Atlassian Cloud hosts, explicit Jira `project_keys` or Confluence `space_keys`, and env/file credential refs. Jira ticket titles are `summary`, so include that field when customizing Jira fields. Rich fields, comments, and Confluence page bodies are ingested only when configured; `projects.integrations.poll` queues async polling, `projects.integrations.poll_status` tracks it, and search/read tools use local graph data only without calling Atlassian. Setup details are in [Local project configuration](docs/configuration/local-projects.md). LadybugDB native imports remain gated behind `scripts/ladybug-libs.sh` and the `ladybug_native system_ladybug` tags. SQLite configuration and persistent graph files must stay local, non-secret, and ignored under `data/` by default. ## Security And Privacy Do not commit real `.env` files, secrets, credentials, raw prompts, raw fetched content, provider payloads, or personal data. General PII ingestion remains prohibited. The only approved exception is local Jira/Confluence rich-content handling under [Project integrations security policy](docs/security/project-integrations.md).