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

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

Loading

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, permission snapshots, and compile-to-Work-Plan refs	Compile-only; TOML never executes directly, import does not run automation, 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.
How Serena, MCP, REST, and shell work together	Agent context server guide.
REST contract	OpenAPI contract.
MCP contract	MCP capability contract.

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.

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

Loading

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. 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.

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

Loading

High-level flow:

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

Loading

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
• Agent context server guide
• System architecture
• REST OpenAPI contract
• MCP capability contract
• Local project configuration
• Local development runbook
• Privacy baseline
• Research data handling

Do not link .ai/tasks/* files or research-plan files from technical docs. They are local, stale-prone working artifacts.

Local Checks

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:

MIVIA_HTTP_ADDR=127.0.0.1:8080 \
MIVIA_SQLITE_PATH=:memory: \
go run ./cmd/mivia-server

Optional local project config:

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:

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:

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:

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_CONTAINER_USER from id -u: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:

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:

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:

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.

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.

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.

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.