These answers route common user tasks to maintained instructions. For exact flags, request schemas, and tool availability, use the help or live discovery surface from the installed revision.
Getting started
Where should I begin?
Follow the quick start. It covers installation, project setup, the first index, and an initial query. Do not copy storage paths or service commands from an older environment without checking the current runbook or CLI help.
Do I need every service for local exploration?
No. Start only the interfaces required by your task. A CLI analysis and an authenticated dashboard exercise have different dependencies. If startup fails, use the current troubleshooting guide rather than treating a stale process list as authority.
Projects and graph freshness
Why must I select a project?
Project scope determines repository context, CPG location, authorization, memory, and evidence binding. An identifier is not permission: authenticated application interfaces resolve the allowed project context on the server.
Why is a result empty or different from the source tree?
Confirm that the expected revision was indexed, the language is supported, exclusions are correct, and project synchronization is current. An empty query can mean “not found,” but it can also mean stale context, incomplete graph coverage, or a scope mismatch.
Analysis and evidence
Which analysis command should I use?
Use the analysis capability map: review for change-oriented findings, impact
for blast radius, patterns for structural search, hypothesis for CPG-backed security hypotheses,
threat-model for trust boundaries, and SCA for dependencies. Run python -m src.cli --help and the
selected subcommand’s --help before scripting it.
Does a clean result prove the release is safe?
No. Analysis is one evidence source. Release decisions also require the acceptance, review, AppSec, QA, documentation, traceability, runtime, and financial-control evidence required by the governed task. Bind results to the exact revision; a path, screenshot, or old label is not enough.
Can CodeGraph apply generated fixes automatically?
Some workflows can propose or prepare changes. Treat generated changes like any other patch: inspect the diff, run focused and regression tests, review security impact, and keep rollback information. A suggestion enters the review and approval workflow before repository mutation or publication.
MCP and digital employees
Why is an MCP tool absent?
Tool visibility depends on the running server, active profile, owner policy, and client connection. Follow the MCP_OPERATOR_GUIDE.md and inspect the live client catalog. A working discovery or invocation confirms runtime registration.
How should structured MCP arguments be passed?
Pass native arrays and objects, not JSON encoded inside strings. Use canonical typed identifiers and explicit project, namespace, story, and task scope. Do not pass raw database paths through agent-facing tools; the runtime resolves storage from the authorized project context.
What do digital employees authorize?
They separate accountable evidence lanes; they do not grant credentials or unlimited mutation rights. See governed digital employees for roles, task capsules, handoffs, and closure. Human approval applies only to its exact signed transition and scope.
Security and data handling
Can repository data be sent to an external LLM?
Only when the deployment’s policy, provider configuration, and data classification allow it. Review LLM_SECURITY.md before enabling a provider. Keep secrets out of prompts, logs, command arguments, fixtures, and public documentation.
Is direct DuckDB access a supported integration?
No. It is a maintainer diagnostic boundary. Use project-scoped CLI, REST, MCP, ACP, or GoCPG interfaces. Direct writes can bypass authorization, schema ownership, freshness checks, and traceability.
Where should I report a suspected vulnerability?
Do not publish exploit details or secrets in a public issue. Follow the private reporting channel defined by the repository security policy, include the affected revision and a minimal safe reproduction, and preserve relevant logs without credentials.
Failures and recovery
What information makes a useful support report?
Include the installed revision, operating system, interface, exact command or request shape, project scope, expected behavior, observed error, and a secret-free log excerpt. State whether the failure is reproducible and whether project context is fresh.
Should I retry a failed governed action with a different task ID?
Not blindly. Read the authoritative status first. Some failures require synchronizing the existing story or task carrier, refreshing evidence, or using a specifically approved recovery transition. Creating a neighboring task can lose continuity without fixing the blocking condition.
Where do I look next?
Use troubleshooting for known operational symptoms, the scenario guide for task routing, and live CLI or MCP discovery for the installed contract. Current source and observed runtime behavior outrank archived examples.