Setup

Diagnose Session Cartographer semantic-search prerequisites and, only with an explicit request to enable or fix them, configure Codex command-network access for the local Qdrant and embedding services.

Resolve ROOT from CARTOGRAPHER_ROOT, CLAUDE_PLUGIN_ROOT, or PLUGIN_ROOT. If none is set, derive the plugin root from this skill's reported base directory (../.. from skills/setup); use the conventional checkout only as a legacy fallback. Verify that $ROOT/scripts/codex-loopback-setup.js exists.

Diagnose first

Run the doctor without modifying user configuration:

node "$ROOT/scripts/codex-loopback-setup.js" doctor --json

Treat sandbox_network_denied as a Codex permission/configuration state, not as evidence that Qdrant or the embedder stopped. If the current task reports network disabled, a host-side HTTP 200 and an in-task connection failure are consistent: the service is healthy but unreachable from this task.

Apply only with consent

Run apply only when the user explicitly asks to enable, configure, or fix access. It updates the user's Codex config, so use the normal approval path when the file is outside the writable workspace:

node "$ROOT/scripts/codex-loopback-setup.js" apply --json

The updater:

• preserves the active Codex permission model instead of mixing legacy sandbox settings with permission profiles;
• enables command networking behind Codex's network proxy;
• adds only exact localhost and 127.0.0.1 allow rules while preserving existing domain policy;
• creates a timestamped backup before changing an existing config; and
• refuses ambiguous or mixed configuration instead of rewriting it.

Never edit config.toml directly or silently broaden the allowlist. After a successful update, tell the user to restart Codex and start a fresh task; permissions are fixed when the task starts. In that fresh task, rerun doctor and require HTTP success for both Qdrant /healthz and the embedder /health before reporting semantic search ready. Keyword-only recall does not require this setup.

Payload indexes

Once Qdrant is reachable and the collection exists, confirm it carries the two payload indexes the semantic leg filters on (project keyword, timestamp datetime). Without them a filtered search costs 200-420 ms on a 157k-point collection instead of 4-16 ms, which is enough to blow the Turbo recall budget. The check is read-first and creates only what is missing; it is safe to run on every diagnosis:

node "$ROOT/scripts/qdrant-collection.js" ensure-indexes --json

created names what this run built; failed means the Qdrant version refused an index type (datetime needs Qdrant 1.8+). Report either verbatim.