NetToolsKit Copilot Workspace

Rust workspace for the NetToolsKit Copilot toolchain, combining CLI commands, runtime orchestration, projected provider surfaces, versioned planning/spec governance, and a durable root knowledge base for local RAG.

Introduction

NetToolsKit Copilot is a multi-crate Rust workspace that currently combines deterministic engineering automation, runtime orchestration, and local-first knowledge/memory under one repository-managed ntk surface.

Objectives:

• Provide a single Rust workspace for deterministic engineering automation, runtime orchestration, and local-first memory surfaces
• Keep repository automation deterministic through versioned projections and planning artifacts
• Preserve local-first operation while supporting projected MCP and editor surfaces
• Keep repository-owned automation on native Rust command boundaries and treat any external shell integration as explicit downstream interoperability rather than a second repo-owned path

Current Simplification Direction

The repository is now being simplified around one frozen platform model:

• Automation: deterministic generation, validation, manifests, and templating
• Control: orchestration, runtime execution, worker flow, and token economy
• Memory: ingestion, retrieval, local memory, and vault projection
• UI: shared interface layer for CLI and terminal presentation
• Shared: minimal contracts, telemetry, and generic tasking
• App: composition root that wires the modules into interactive CLI and explicit ntk commands

The current documentation checkpoint treats crates/app/{entrypoint,help}, crates/shared/{contracts,telemetry,tasking}, crates/ui/{cli,terminal}, crates/automation/{codegen,manifest,templating,validation,security,governance,maintenance}, crates/control/{orchestrator,worker}, and crates/memory/engine as the preferred consumer-facing crates. The remaining historical crates stay in the workspace as transitional implementation hosts or compatibility facades while production wiring continues to migrate, so the simplified model above stays both the architectural target and the default documentation posture. shared/contracts owns the runtime surface contract catalog, and control/runtime is documented only as a compat facade over contracts::* after the runtime-local host was removed without residue.

Package Readiness

Copilot is not ready for npm/npx publication yet. The target package is @nettoolskit/copilot with a future ntk-copilot command, but the current repository still exposes ntk, copilotctl, and internal service binaries with ambiguous publication boundaries.

See Copilot Package Readiness for the required crate and CLI cleanup before publishing.

Features

• ✅ Rust crates for CLI entry points, orchestration, commands, telemetry, runtime validation, and UI boundaries
• ✅ Explicit ntk startup classes plus dedicated service-launch and interactive-launch bootstraps so runtime, validation, AI reporting, completions, HTTP service mode, and the default TUI entrypoint each cross their own startup boundary instead of sharing one inline main.rs path
• ✅ Versioned projection model for .github/, .codex/, .claude/, and .vscode/
• ✅ Native MCP runtime projection and Codex config application from a canonical catalog
• ✅ Native ntk codegen inspect|plan|apply surfaces for structural repository inspection plus deterministic generation from the canonical multi-stack codegen catalog
• ✅ Rust-owned nettoolskit-knowledge foundation crate plus ntk knowledge query|explain|build-vault, covering md/txt/json/html normalized ingestion, deterministic stable_id/content_hash, overlap-aware chunking, provider-agnostic embedding contracts, the repository-local SQLite knowledge store under .build/knowledge/store/knowledge.db, SQL-side sqlite-vec ranking as the forward vector retrieval path with explicit preflight readiness diagnostics when the capability is unavailable, a local-first graph lane materialized into an in-memory repository per workspace instead of a second persisted engine, an explicit orchestration seam through materialize_workspace, query_materialized, query_materialized_verified, and build_vault_from_materialized, repository-owned command-catalog augmentation inside the materialization seam, final package budgets for snippets/evidence/graph edges, typed materialized-workspace caches for retrieval/context/verified-result reuse, and documented persistence-profile targets for Profile A (SQLite + sqlite-vec) plus Profile B (PostgreSQL + pgvector + pg_trgm + pgAudit, still planned in crates/knowledge), bounded hybrid context packaging, grouped knowledge-record vault projection aligned to the external knowledge-base contract, graph-aware backlinks/related sections, and a generated vault manifest
• ✅ Native ntk runtime scaffold-workstream, ntk knowledge scaffold-record, and ntk validation knowledge-base now govern dated plan/spec creation plus semantic .knowledge-base authoring and validation through repository-owned templates and typed control-plane output
• ✅ Canonical definitions/instructions/** now carry the repository metadata envelope while definitions/templates/** is payload-first: instruction sources preserve applyTo and priority, template semantics live in instructions plus central manifests/catalogs, and projected .github/templates/** plus .github/prompts/poml/** stay consumer-focused without canonical template metadata wrappers
• ✅ The canonical codegen lanes now use a stable codebase/ contract across .NET, frontend, and Rust, while .NET further separates reusable payload seeds from explicit architecture/clean-architecture/src, architecture/clean-architecture/tests, and architecture/vertical-slice/** lanes for architecture-specific scaffolds
• ✅ Deployment assets now follow one simplified repository-owned topology: deployment/docker/** for Compose manifests, deployment/env/** for versioned env contracts, deployment/shared/** for reusable reverse-proxy, persistence, and MCP Gateway payloads, and root-owned runtime/deployment data under .deployment/**
• ✅ Native ntk runtime capture-change-evidence and ntk validation ai-change-evidence now give AI-assisted, non-trivial changes a repository-owned evidence/capture gate with typed JSON output, git-inferred touched paths, and versioned change-evidence templates
• ✅ Native ntk validation command-surface-evidence now validates deterministic terminal-evidence coverage under .build/evidence/command-surface/**, and shared validation profiles surface the same gate through validate-all
• ✅ Runtime bootstrap now exposes the selected provider-surface projection summary instead of hiding projection behind a generic boolean
• ✅ Native ntk runtime clean-codex-runtime and ntk runtime clean-vscode-user-runtime now own retained Codex and VS Code user-runtime cleanup behavior and expose typed JSON control schemas
• ✅ Codex session titles are normalized on SessionStart with the current workspace prefix through the managed wrapper/command lane, keeping %USERPROFILE%\\.codex\\session_index.jsonl and %USERPROFILE%\\.codex\\state_5.sqlite aligned without blocking startup when normalization fails
• ✅ Native ntk runtime super-agent-housekeeping now owns Super Agent continuity refresh, cleanup-step dispatch, and record-only housekeeping output without a local PowerShell launcher
• ✅ Native ntk runtime new-super-agent-worktree now owns deterministic Super Agent worktree planning and creation and exposes a typed JSON control schema
• ✅ Authored orchestration and worktree guidance now uses ntk runtime new-super-agent-worktree, run-agent-pipeline, resume-agent-pipeline, replay-agent-run, and evaluate-agent-pipeline directly across the repository-owned runtime lane
• ✅ Local context index with shared deterministic lexical SQLite/JSON recall ranking, cheap context reranking, budget-aware context admission before prompt packing, selection/drop diagnostics, and weekly AI usage ledger for deterministic repo recall
• ✅ Repository-local SQLite memory now has v3 vector and graph schema foundations under .temp/context-memory/context.db: chunk_embeddings for future sqlite-vec-compatible vectors plus memory_nodes and memory_edges for graph traversal through official SQLite recursive CTE support; read-local-memory exposes the read-only SQLite capability snapshot, while query-local-memory stays lexical by default and does not emit that snapshot until a real hybrid backend exists
• ✅ Built-in AI provider profiles plus ntk ai doctor diagnostics, smart routing strategy scoring, normalized adapter contracts, canonical agent/skill model-routing defaults, matrix-aware usage reporting with typed weekly budget warning status, and tighter low-risk cache/output/compaction/replay token policy for AI surfaces
• ✅ Live /ai control-loop evidence on the supported runtime path now classifies ingress, persists ai-route-decision and ai-route-outcome events, and emits typed execution-state snapshots plus transition receipts into the repository-local continuity SQLite store under .temp/context-memory/
• ✅ Live /ai runtime outcome tracing now correlates route decisions with local cache replays, Memory verified-answer cache replays, provider success/failure, answer-evidence verifier posture, retries, failovers, and metadata-only artifact refs while excluding prompts, answers, snippets, provider payloads, verification tokens, local paths, and secrets
• ✅ control/orchestrator now exposes a deterministic decision-runtime contract for OrchestrationRequest, OrchestrationPlan, DecisionTrace, and ExecutionEnvelope, planning agent policy references, model lane posture, ordered memory capability requests, bounded memory.context.package execution plans, approval gates, and replay evidence without importing downstream agent or memory implementation crates
• ✅ control/orchestrator now publishes data-only Agentic RAG decision contracts for query rewrite intent, context need, source-lane selection, retry budgets, validation requirements, and final evidence gates, with nettoolskit-det modeled as a disabled/unavailable typed lane until a real deterministic source contract is connected
• ✅ control/orchestrator now evaluates Agentic RAG policy gates and deterministic loop simulations for tenant/scope, workspace boundary, secret material, budget, rate limit, internet approval, dry-run, audit events, retry, provider handoff, and final-answer next action without executing memory, DET, provider, or internet work
• ✅ control/orchestrator now models Agentic RAG HyDE delegation as memory-owned policy plus deterministic answer-readiness reports over relevance, groundedness, citation coverage, evidence metadata, and final gate state without parsing provider answers or executing retrieval
• ✅ control/orchestrator now produces Agentic RAG metadata-only audit log records and validates a mocked full-loop acceptance path across HyDE delegation, policy gating, source selection, answer readiness, memory package refs, deterministic function refs, provider lane refs, and final next action without storing raw query or answer text
• ✅ control/orchestrator now exposes an opt-in Agentic RAG live acceptance gate that composes ntk-memory context-package, ntk-harness runtime-stream, ntk-memory groundedness-validate, and optional verified-answer cache writes through CLI runner seams, with enterprise env readiness checks and metadata-only Memory, Harness, groundedness, cache, and audit refs
• ✅ control/orchestrator now attaches data-only adaptive memory request context and query-planning signals for RAG/CAG/HyDE decisions, including tenant/scope posture, bounded query normalization, subqueries, domain, ambiguity, HyDE eligibility, and DecisionStage::QueryPlanning trace evidence without executing retrieval inside Copilot
• ✅ control/orchestrator now selects adaptive memory paths before execution, covering cag_hit, simple, intermediate, and advanced plans with stable reasons, typed cache-hit validation signals, short-circuit safeguards, and DecisionStage::AdaptivePathSelection trace evidence while keeping retrieval/rerank/compression/validation execution behind nettoolskit-memory
• ✅ control/orchestrator now applies conditional HyDE policy from data-only retrieval confidence, query ambiguity, domain risk, supplied hypotheses, explicit mode, and force/disable flags, avoiding blanket HyDE execution when retrieval confidence is already high
• ✅ control/orchestrator now plans and enforces answer evidence policy with minimum evidence refs, source-score gates, citation requirements, groundedness validation requirements, allowed evidence kinds, missing-evidence behavior, replayable policy reasons, and a metadata-only allow/gap/retry/block report before downstream answer assembly
• ✅ control/orchestrator now plans bounded route-decision observability with rationale-free stage metrics, stable route labels, redacted payload fields, and a dedicated route evidence artifact path without copying prompts, transcripts, snippets, secrets, or absolute local paths
• ✅ control/orchestrator now emits EvidencePlan.gatewayAdmission, a typed metadata-only admission decision for tenant/scope, auth posture, rate and budget controls, trace correlation, observability evidence roots, and feature flags before adaptive model, memory, provider, and cache stages run
• ✅ control/orchestrator now emits EvidencePlan.adaptivePipeline, a generic harness-compatible AI architecture decision that maps Copilot gateway, cache, route, query, HyDE, retrieval, rerank, compression, provider, groundedness, verified-cache-save, and report stages without importing nettoolskit-harness
• ✅ control/orchestrator now plans adaptive memory-stage execution bindings for available CLI capabilities, embedded context-package work, caller-owned cache evidence, skipped stages, and contract-pending stages without inventing unsupported memory-service commands
• ✅ control/orchestrator now publishes the memory.groundedness.validate capability, maps groundedness validation stages to the external ntk-memory groundedness-validate CLI boundary, and binds rerank plus contextual compression as embedded memory.context.package work through schema-compatible operational toggles
• ✅ control/orchestrator now accepts ntk-memory manifest and doctor JSON as a data-only MemoryRuntimeCapabilitySurface, uses the current published contract as the default fallback, and degrades optional memory stages and payload toggles when external capabilities or readiness lanes are unavailable without linking to the memory implementation crate
• ✅ Explicit agentic surface separation for MCP, A2A, RAG, and CAG
• ✅ Canonical internal multi-agent runtime contract for leader-worker lineage, inheritance, mailbox semantics, and approval-bridge boundaries without conflating internal delegation with A2A
• ✅ Versioned control-plane inspection schemas for AI profile/model-routing inventory, doctor, healthcheck, self-heal, validation orchestration, build/task-output/local-memory maintenance, and local recall machine output, including MCP review-action guidance for operator follow-up, bounded readiness evidence when Codex MCP auth placeholders have already been materialized in the inspected config, native --mcp-input ID=VALUE remediation through sync/bootstrap/self-heal for fresh auth replacement, and typed retry-follow-up recovery-versus-residual state for retry-only MCP self-heal debt
• ✅ Native runtime bootstrap, install-planning, and install-execution surfaces with typed JSON control contracts, so onboarding target resolution, runtime-profile selection, git-hook EOF planning, and the final onboarding step loop no longer depend on any repository-owned PowerShell wrapper
• ✅ Native ntk runtime bootstrap, ntk runtime plan-install, and ntk runtime install now own repository-managed onboarding and sync orchestration directly as the sole repo-owned onboarding path
• ✅ Authored runtime-sync guidance, provider skills, and post-commit reminders now recommend ntk runtime bootstrap and ntk runtime install directly across the repository-owned onboarding lane
• ✅ Repository workflow shell/git execution now streams large stdout and stderr through a bounded task-output boundary that keeps small output inline, spills larger output under .build/task-output/, persists sidecar metadata, exposes ntk runtime inspect-task-output for bounded readback, and prunes retained artifacts through ntk runtime prune-task-output
• ✅ Native ntk runtime evaluate-agent-pipeline now evaluates the canonical orchestration pipeline against versioned fixtures, writes a scorecard under .temp/agent-evals/, exposes a typed JSON control schema, and owns the evaluation lane directly
• ✅ Native ntk runtime run-agent-pipeline now executes the canonical orchestration pipeline against the authored stage graph, writes managed run artifacts under .temp/agent-runs/, exposes a typed JSON control schema, and owns the execution lane directly without a local PowerShell launcher
• ✅ control/orchestrator plans ntk-memory doctor, materialize, query, context-package, groundedness-validate, vault-materialize, cache write/read/prune, reusable memory-record write/read/promote/prune, and local-memory write/read/prune calls through the memory_cli adapter boundary, keeping RAG/HyDE readiness, groundedness checks, durable CAG/cache, reusable memory, operational-memory, vault artifacts, and generated artifacts under orchestrator control without linking to the memory implementation crate
• ✅ control/orchestrator executes planned ntk-memory calls through an injected runner seam, writes bounded request payloads, validates JSON outputs, records replayable memory evidence under .deployment/artifacts/memory/{trace}, and lets the default process runner pin a packaged executable through NTK_MEMORY_CLI_PATH
• ✅ Copilot is compatible with the current nettoolskit-memory verified-answer scope contract: verified-answer cache lookup queries each routed provider scope in order, accepted-answer writes use the provider scope that actually generated the response, and all answer_generation_scope identifiers are safe metadata only (provider_id, model_id, model_version, with runtime-selected as the model-version sentinel when no provider revision is exposed); these identifiers must not carry secrets, prompts, tokens, local paths, provider payloads, or raw provider configuration
• ✅ ntk runtime memory-doctor now preflights the external ntk-memory doctor service through the orchestrator boundary with bounded output and evidence artifacts
• ✅ ntk runtime memory-materialize now builds local-first knowledge materialization requests under .build/requests/memory/{trace} and executes ntk-memory materialize through the same evidence-backed runtime boundary
• ✅ ntk runtime memory-query now executes evidence-backed ntk-memory query requests with HyDE and graph expansion enabled by default for local-first RAG/context-package retrieval, optional caller-owned verified answer reuse, and cache-hit evidence in the JSON schema
• ✅ ntk runtime memory-context-package now executes evidence-backed ntk-memory context-package requests for bounded RAG/CAG/HyDE context packages without answer text, accepts caller-supplied HyDE hypothesis JSON through --supplied-hyde, and the decision runtime can now plan the same context-package path as model/tool execution input
• ✅ control/orchestrator now forwards caller-owned supplied HyDE hypotheses as data-only supplied_hyde_hypothesis payloads to ntk-memory without importing the memory crate or leaking prompt, model, credential, retry, or provider-policy ownership into the memory boundary
• ✅ control/orchestrator now exposes a harness-backed AI provider selectable by /ai through NTK_AI_PROVIDER=harness, with ntk-harness runtime-stream bounded request/output/evidence artifacts, injected-runner tests, public enterprise live acceptance gated by NTK_HARNESS_ENTERPRISE_E2E=1 plus NTK_HARNESS_CLI_PATH, and backward-compatible low-level live execution through NTK_HARNESS_CLI_LIVE=1
• ✅ control/orchestrator can now plan and opt-in emit ntk-harness efficiency-observation request/output artifacts from live /ai memory-assisted executions, preparing memory-gain telemetry for analytics without importing nettoolskit-harness implementation code
• ✅ ntk runtime machine-worker once|run now supports explicit --fleet-store-path durable JSON state for local fleet readiness, heartbeat, shutdown, and task lease mutations while keeping --fleet-state-path as a read-only in-memory snapshot fixture
• ✅ ntk runtime machine list|inspect and ntk runtime task list|inspect can inspect either read-only --fleet-state-path snapshots or durable --fleet-store-path JSON stores, with mutual-exclusion checks and lease-token redaction in task schemas
• ✅ ntk runtime memory-cache-*, memory-record-*, memory-local-*, and memory-vault-materialize now expose memory adapter commands through opaque JSON payload files, generated request artifacts, output artifacts, and replayable evidence without importing the memory implementation crate
• ✅ ntk runtime memory-groundedness-validate now exposes a typed groundedness validation facade over ntk-memory groundedness-validate, accepting caller-owned answer files, context-package JSON, and deterministic profile JSON while returning metadata-only status, score, count, checksum, and evidence paths without echoing answer or context content
• ✅ control/runtime now exposes a metadata-only memory evidence replay gate that validates ntk-memory command, capability, request path, output path, checksum, byte length, JSON validity, and adapter success for query, context-package, and opaque memory payload commands
• ✅ AI runtime prompt assembly can auto-prepare RAG/CAG/HyDE context packages when NTK_AI_MEMORY_CONTEXT_MODE=rag|cag|hyde and source roots or paths are configured, then consume the artifact through a request-scoped aiInjectionEnv bridge or the compatibility NTK_AI_MEMORY_CONTEXT_PACKAGE_OUTPUT fallback while retrieval remains owned by nettoolskit-memory
• ✅ control/orchestrator now has an opt-in enterprise memory-to-harness acceptance gate using NTK_MEMORY_ENTERPRISE_E2E=1, the real configured ntk-memory CLI selected by NTK_MEMORY_CLI_PATH, request-scoped aiInjectionEnv, fail-closed ntk-memory doctor readiness, and a captured harness runtime-stream payload to prove bounded answer-free context reaches the downstream provider boundary without live model calls or local path leakage
• ✅ The decision runtime can now execute its planned memory.context.package request through the memory CLI runner seam and return typed request/output/evidence paths, output checksum metadata, retrieval mode, snippet count, and the bounded answer-free context message for downstream prompt assembly
• ✅ Live /ai memory context now has a post-provider verified-answer evidence closeout gate: Copilot buffers provider output while the gate is active, executes ntk-memory groundedness-validate when the selected answer policy requires it, enforces context-package evidence plus groundedness metadata before printing or persisting the answer, calls Memory-owned verified-answer-cache-write for accepted answers, bypasses the local unverified response cache, and writes a metadata-only answer-evidence-closeout.json under .deployment/artifacts/memory/{trace} while ntk-memory remains the owner of RAG/CAG/HyDE execution and durable cache persistence
• ✅ Live /ai memory context can reuse Memory-owned verified answers before provider execution when a prepared memory context exists: Copilot queries ntk-memory query, accepts only cache_status.verified_idempotent_result_cache_hit=true with non-empty answer_text, records the replay as non-billable cache reuse, binds the verification token to the current answer-evidence policy, and leaves cache keys plus payload hashing owned by Memory
• ✅ ntk runtime decision-memory-context now bridges an OrchestrationRequest JSON file to the decision-planned memory.context.package execution and emits bounded AI injection environment hints without returning raw context text
• ✅ Native orchestration validation stage now runs inside the Rust runtime, retiring the PowerShell validate-stage wrapper
• ✅ Native intake/spec/plan/route/implement/review/closeout stages now execute fully in Rust, retiring the remaining scripts/orchestration/stages/*.ps1 wrappers
• ✅ Native ntk runtime resume-agent-pipeline now resumes a managed run directly from checkpoint state and request artifacts, exposes a typed JSON control schema, preserves native approval-state reporting, and owns the resume lane directly without a local PowerShell launcher
• ✅ Native ntk runtime replay-agent-run now replays canonical run artifacts, traces, policy evaluations, and checkpoint state into a typed JSON control schema, optionally persists a managed replay summary, and owns the replay lane directly
• ✅ Deterministic planning, specification, and reference docs under planning/ plus a canonical durable knowledge base under docs/knowledge-base/
• ✅ Repository-owned runtime smoke validates the native runtime path; any external target-repository script mode is explicit and non-default

Contents

• Introduction
• Features
• Contents
  • Command Reference
  • Architecture
  • Control Plane Model
  • Task Output Model
  • Crates
  • Compatibility and Support
  • Operations
  • Planning
  • Governance and Security
• Build and Tests
• Contributing
• Dependencies
• References
• License

Command Reference

Run ntk --help for the current top-level surface. If no command is provided, ntk [PROMPT] starts the interactive CLI.

Top-Level Commands

| Surface | Command | Description | | --- | --- | --- | | Interactive | ntk [PROMPT] | Launch the interactive CLI when no explicit subcommand is supplied | | Codegen | ntk codegen | Inspect repository structure and execute deterministic code-generation flows | | Knowledge | ntk knowledge | Execute local knowledge query, explain, and vault-materialization flows over the bounded nettoolskit-knowledge surface | | Manifests | ntk manifest | Manage and apply manifests | | AI | ntk ai | Execute AI-focused command surfaces | | Runtime | ntk runtime | Execute repository runtime hook and maintenance surfaces | | Validation | ntk validation | Execute native repository validation checks | | Completions | ntk completions <shell> | Generate shell completions for bash, elvish, fish, powershell, or zsh | | Service | ntk service | Run background HTTP service mode |

Manifest Commands

| Command | Description | | --- | --- | | ntk manifest list | Discover available manifests in the workspace | | ntk manifest check | Validate manifest structure and dependencies | | ntk manifest render | Preview generated files without applying changes | | ntk manifest apply | Apply a manifest file to generate or update files |

AI Commands

| Command | Description | | --- | --- | | ntk ai doctor | Diagnose active AI profile, provider chain, routing strategy, adapter contracts, timeout, and remote readiness without executing a request, with a typed JSON control schema for machine consumers | | ntk ai runtime inventory | Show read-only provider pool, model catalog, local runtime, and Open WebUI bootstrap metadata with redacted sources | | ntk ai model-routing list | List canonical agent and skill model-routing defaults consumed by the development orchestrator | | ntk ai model-routing show | Show the resolved active agent/skill routing selection or an explicit lane pairing | | ntk ai profiles list | List built-in AI provider profiles and their provider-mode classifications | | ntk ai profiles show [profile] | Show one AI provider profile or the active NTK_AI_PROFILE preset | | ntk ai usage weekly | Report one ISO week of persisted local AI usage history plus the active runtime route, routing posture, and compatible free-provider families | | ntk ai usage summary | Report a bounded recent multi-week summary of persisted local AI usage history plus the active runtime route, routing posture, and compatible free-provider families |

Codegen Commands

| Command | Description | | --- | --- | | ntk codegen inspect | Inspect a repository stack through the structural-intelligence boundary and emit human or JSON summaries | | ntk codegen plan | Build an explainable deterministic generation plan from the canonical template catalog without writing files |

Knowledge Commands

| Command | Description | | --- | --- | | ntk knowledge query | Ingest selected local files, assemble a bounded hybrid ContextPackage, and emit a deterministic answer summary or JSON result | | ntk knowledge explain | Run the same bounded local knowledge pipeline but print the effective query, retained evidence, and answer surface explicitly | | ntk knowledge build-vault | Materialize grouped Obsidian-compatible Markdown notes plus knowledge-vault.manifest.json for the selected local knowledge sources | | ntk codegen apply | Apply a deterministic generation request with collision-policy handling and validation hints |

ntk knowledge query|explain|build-vault now materialize bounded workspace state explicitly in the CLI before query or vault projection. The sole forward orchestration seam in nettoolskit-knowledge is materialize_workspace, query_materialized, query_materialized_verified, and build_vault_from_materialized.

That materialization seam now also augments the corpus with the single repository-owned command-catalog.json when present, applies final package budgets for snippets, evidence items, and retained graph edges through ContextPackageQuery, and keeps typed in-memory caches for retrieval results, context packages, and verified idempotent answers scoped to the materialized workspace instead of replaying the whole hybrid pipeline for every repeated read.

ntk knowledge query and ntk knowledge explain also run a repository-owned sqlite-vec readiness preflight before materialization, so a missing forward vector capability fails early with a typed diagnostic instead of surfacing as a late vec0 error during semantic retrieval.

The local-memory read surface exposes the read-only SQLite capability snapshot. The query surface stays lexical by default and keeps that snapshot out of the per-query path until the backend genuinely supports a hybrid read model.

The repository-owned local-first path is SQLite + sqlite-vec with graph expansion materialized in-memory for each workspace. No native Kuzu toolchain or second embedded graph store is part of the forward contract.

Project-local runtime memory is separate from the .build/knowledge/store/knowledge.db knowledge store: it lives at .temp/context-memory/context.db, currently uses SQLite schema v3, stores vector-ready chunk_embeddings, and models graph state with memory_nodes/memory_edges. Traversal is planned through SQLite's official WITH RECURSIVE graph-query support rather than a dedicated graph database.

AI runtime memory context injection is file-artifact based. ntk runtime decision-memory-context --request <orchestration-request.json> --json-output is the deterministic bridge that can produce the .deployment/artifacts/memory/**/*.json package and its aiInjectionEnv hint from a decision-runtime request. Live /ai can perform that bridge automatically when NTK_AI_MEMORY_CONTEXT_MODE=rag|cag|hyde is set with NTK_AI_MEMORY_CONTEXT_SOURCE_ROOTS or NTK_AI_MEMORY_CONTEXT_SOURCE_PATHS; it passes the resulting map into the scoped AI request-context bridge instead of mutating process-global env. With NTK_AI_PROVIDER=harness, that injected system message is serialized into the downstream ntk-harness runtime-stream request artifact before execution. Manual workflows can still set NTK_AI_MEMORY_CONTEXT_PACKAGE_OUTPUT and optionally NTK_AI_MEMORY_CONTEXT_MAX_SNIPPETS. The runtime reads and renders the bounded answer-free artifact; it does not own retrieval, ranking, graph expansion, HyDE, or CAG/cache execution. After the answer evidence gate allows output, Copilot forwards only the original memory query payload plus provider answer text to ntk-memory verified-answer-cache-write; Memory rebuilds context, validates groundedness, computes durable keys and hashes, and persists verified cache state.

OrchestrationRequest.requestContext carries adaptive memory policy signals as data-only control-plane fields: tenantId, scopeId, roleRefs, permissionPosture, budget, cacheHit, retrievalConfidence, featureFlags, traceId, and evidenceRoot. CAG/cache reuse fails closed without explicit tenant, scope, role, permission posture, and a caller-owned validated cacheHit signal, and the contract does not import nettoolskit-memory or ntk-harness implementation DTOs.

EvidencePlan.gatewayAdmission turns request-context signals into a typed entry-control decision before route planning. It records only metadata for tenant/scope posture, auth posture, bounded rate and budget controls, trace correlation, observability evidence roots, and feature-flag labels. It does not carry credentials, prompts, answers, snippets, provider payloads, Memory cache internals, connection strings, secrets, or absolute local paths.

AdaptiveMemoryPathPlan selects the cheapest safe context path before memory execution. A validated scoped CAG hit can short-circuit memory execution; otherwise the runtime degrades through simple, intermediate, or advanced plans based on query ambiguity, subqueries, domain, conditional HyDE eligibility, and feature flags. Low retrieval confidence, high ambiguity, explicit HyDE mode, supplied HyDE hypotheses, and risky medium-ambiguity domains can escalate to HyDE, while high retrieval confidence suppresses non-explicit HyDE. The path selector records planned and skipped stages as contract data only, so actual retrieval, rerank, compression, groundedness validation, cache persistence, and storage remain owned by nettoolskit-memory.

MemoryDecisionPlan.stagePlan turns those adaptive stages into explicit execution bindings. Stages with existing CLI contracts map to ntk-memory commands, HyDE is marked as embedded in the knowledge-query capability, scoped CAG hits are marked as caller-owned cache evidence, skipped stages stay explicit, groundedness validation maps to memory.groundedness.validate through ntk-memory groundedness-validate, and rerank plus contextual compression are marked as embedded memory.context.package work because nettoolskit-memory exposes them as operational fields on the context-package request.

MemoryRuntimeCapabilitySurface lets the same planner accept external ntk-memory manifest and ntk-memory doctor JSON without importing memory implementation types. The manifest proves capability and contract existence; the doctor report proves runtime readiness through capability statuses and lanes. plan_orchestration_decision uses the current published memory contract as a deterministic fallback, while plan_orchestration_decision_with_memory_surface can degrade unsupported optional stages to contract_pending and disable unsupported request toggles.

EvidencePlan.answerPolicy is also data-only. It selects the answer evidence policy before provider execution, including whether evidence is required, minimum refs, minimum source score, citation and groundedness validation gates, allowed evidence kinds, missing-evidence behavior, and policy reasons. enforce_answer_evidence_policy converts that policy plus retained evidence-reference metadata into an explicit allow, gap-disclosure, retry, or block report for downstream answer assembly. The decision runtime still does not parse memory output, snippets, model answers, prompts, transcripts, or provider payloads.

Required answer evidence policies always require retained, citable evidence references and a non-zero source-score gate. Legacy decision envelopes without answerPolicy deserialize to an optional compatibility policy so old replay artifacts remain readable while new plans stay stricter.

EvidencePlan.routeDecision records the bounded route-decision observability plan. It emits stable metric names for decision stages, a route label built from task/memory/path/model/approval/evidence posture, retained signal labels, a route evidence artifact path, and explicit payload redaction flags. The contract is intentionally rationale-free and text-free: it does not copy task summaries, query text, source paths, prompts, transcripts, stdout/stderr, provider payloads, connection strings, secrets, or absolute local paths.

EvidencePlan.adaptivePipeline records the generic AI architecture decision in a shape compatible with nettoolskit-harness: cacheHit, simple, intermediate, or advanced path plus ordered gate, cacheLookup, route, plan, retrieve, rerank, compress, generate, validate, cacheSave, and report stages. It is a Copilot-owned decision artifact, not a harness-owned RAG orchestrator, and it keeps service-specific RAG/CAG/HyDE policy outside nettoolskit-harness.

Live /ai also writes a post-execution runtime outcome trace under .deployment/artifacts/ai/runtime-outcomes/** and into repository-local continuity memory as ai-runtime-outcome-trace. The trace correlates ai-route-decision with local cache hits, Memory verified-answer cache hits/misses/errors, provider success/failure, answer-evidence policy status, verified-cache-save metadata, retries, failovers, and final verifier kind without copying prompts, answers, snippets, provider payloads, verification tokens, connection strings, secrets, or absolute local paths.

When NTK_AI_MEMORY_GAIN_OBSERVATION_ENABLED=1, live /ai memory-assisted success paths also write a harness-compatible efficiency-observation.json request under .build/requests/harness/{trace}/. The payload compares the pre-memory request shape with the assisted request shape, includes only token estimates and generic counters such as context hits, cache hits/lookups, and deterministic tool-call count, and keeps prompts, answers, snippets, provider payloads, local paths, and secret material out of the artifact. Setting NTK_AI_MEMORY_GAIN_OBSERVATION_EXECUTE_HARNESS=1 additionally attempts the bounded ntk-harness efficiency-observation execution path, subject to the existing harness live-execution gate.

Enterprise acceptance of the external memory service is explicit and opt-in. Set NTK_MEMORY_ENTERPRISE_E2E=1 before running the runtime acceptance test to exercise the real ntk-memory binary for manifest, doctor, RAG/CAG/HyDE context-package, and decision-memory-context flows. Set NTK_MEMORY_CLI_PATH to the compiled ntk-memory executable when the runtime should use a packaged or pinned binary directly instead of resolving ntk-memory from PATH. When the memory doctor reports only sqlite_vec.semantic_query as degraded, the acceptance test records the fail-closed readiness boundary and skips live RAG/CAG/HyDE execution because the semantic vector backend is not available on that machine.

Runtime Commands

| Command | Description | | --- | --- | | ntk runtime session-start | Build the startup hook payload for VS Code SessionStart, including startup controller selection, workspace-mode guidance, planning/spec continuity references, and EOF policy context | | ntk runtime subagent-start | Build the startup hook payload for VS Code SubagentStart, including worker-type guidance, workspace-mode context, and planning/spec continuity references | | ntk runtime pre-tool-use | Normalize hook payloads for VS Code PreToolUse | | ntk runtime doctor | Run the native runtime doctor workflow, with human-readable output or a typed JSON control schema that includes MCP review categories, aggregated review-category counts, review-reason codes, review-action codes, Codex config application-versus-content-drift state, bounded readiness evidence for already-materialized ${input:...} auth values, unmanaged Codex config drift, and auth-aware loopback HTTP live-probe evidence, including bounded retry-aware retry_request probing with typed live_probe_attempt_count, recovered-versus-exhausted retry detail, 401/403 auth rejection when the applied local credential still fails, and WWW-Authenticate-driven session_expired classification for expired local MCP sessions | | ntk runtime healthcheck | Run the native runtime healthcheck workflow, with human-readable output or a typed JSON control schema, and escalate MCP review-required, unmanaged Codex config drift, or unreachable loopback live-probe findings from ntk runtime doctor, including the failing MCP server id plus structured review category, review reason, action code, or probe detail in the degraded summary | | ntk runtime self-heal | Run the native runtime self-heal workflow, with human-readable output or a typed JSON control schema that runs a strict follow-up runtime healthcheck, preserves its failing detail, performs one bounded extra retry-only follow-up when the residual MCP debt is purely retry_runtime_mcp_request, and carries a typed MCP remediation summary with effective MCP config-apply state, residual manual-review action codes, structured post-healthcheck MCP review server/category/reason/action guidance, support for fresh --mcp-input ID=VALUE auth/session replacement, plus retry follow-up attempted/recovered state and post-retry residual server/category/reason/action detail when live retry debt remains or clears | | ntk runtime bootstrap | Synchronize canonical runtime/provider surfaces into the selected runtime targets and optionally apply MCP configuration, with a typed JSON control schema that preserves the selected projection summary and supports fresh --mcp-input ID=VALUE material when applying Codex MCP config | | ntk runtime plan-install | Build the native onboarding/install step plan consumed by the repository-owned Rust install flow, with a typed JSON control schema that echoes runtime profile, targets, git-hook EOF selection, and ordered managed-runtime steps | | ntk runtime install | Execute the native onboarding/install flow, with human-readable output or a typed JSON control schema that preserves the plan echo, per-step execution state, overall status, and exit code | | ntk runtime install-security-audit-prerequisites | Prepare .NET, frontend, and Rust security-audit prerequisites with optional safe remediation attempts, plus a typed JSON control schema that reports platform, package-manager selection, and per-check readiness before and after remediation | | ntk runtime pre-build-security-gate | Run the native aggregated .NET, frontend, and Rust dependency vulnerability gate with optional prerequisite setup, consolidated Markdown/JSON evidence, and a typed JSON control schema for the multi-stack summary | | ntk runtime clean-build-artifacts | Discover and optionally remove .build, .deployment, bin, and obj artifact directories under the selected path, with measured byte totals for the cleanup footprint and an optional typed JSON control schema | | ntk runtime update-shared-script-checksums-manifest | Regenerate the authored shared-script checksum manifest from the selected included roots, with deterministic SHA-256 entries and an optional typed JSON control schema | | ntk runtime set-branch-protection | Validate or apply the authored GitHub branch-protection baseline through gh api, with a typed JSON control schema for expected/current snapshots plus repository and branch echo | | ntk runtime clean-codex-runtime | Discover and optionally remove retained Codex tmp, log, vendor, and session artifacts under the selected Codex runtime root, with a typed JSON control schema and optional planning-summary export | | ntk runtime clean-vscode-user-runtime | Discover and optionally remove retained VS Code user-runtime artifacts such as stale workspaceStorage, expired chat/transcript/history files, oversized workspace indexes, and backup debris, with a typed JSON control schema and optional planning-summary export | | ntk runtime update-codex-chat-titles | Normalize persisted Codex thread titles with workspace-derived prefixes, with preview/apply modes, current-thread selection, and synchronized JSONL plus SQLite updates | | ntk runtime update-copilot-chat-titles | Normalize persisted VS Code Copilot chat titles with workspace-derived prefixes, with preview/apply modes, optional backup creation, and optional JSON summary output | | ntk runtime update-local-context-index | Build or refresh the repository-owned local context index, with an optional typed JSON control schema for automation consumers | | ntk runtime query-local-context-index | Query the repository-owned local context index through the canonical SQLite recall path, with explicit non-default inspection flags when needed | | ntk runtime update-local-memory | Build or refresh the repository-owned SQLite local memory snapshot, with an optional typed JSON control schema for automation consumers | | ntk runtime read-local-memory | Read recent provider-agnostic continuity events and sessions from the repository-owned SQLite local memory snapshot without changing search semantics | | ntk runtime query-local-memory | Query the repository-owned SQLite local memory snapshot through the default lexical FTS path; future vector/graph hybrid retrieval remains opt-in | | ntk runtime memory-doctor | Execute ntk-memory doctor through the orchestrator memory CLI boundary and write bounded readiness evidence under .deployment/artifacts/memory/{trace} | | ntk runtime memory-materialize | Execute ntk-memory materialize through the orchestrator memory CLI boundary and write request/output/evidence artifacts under .build/requests/memory/{trace} and .deployment/artifacts/memory/{trace} | | ntk runtime memory-query | Execute ntk-memory query through the orchestrator memory CLI boundary with RAG/HyDE/context-package evidence, optional --verification-token verified answer reuse, and optional --supplied-hyde <json> caller-owned HyDE input | | ntk runtime memory-context-package | Execute ntk-memory context-package through the orchestrator memory CLI boundary, optionally forwarding --supplied-hyde <json>, and return context-package evidence without answer text | | ntk runtime memory-groundedness-validate | Execute ntk-memory groundedness-validate through the orchestrator memory CLI boundary from --answer-file, --context-package, and --profile inputs, returning metadata-only validation evidence | | ntk runtime memory-cache-write/read/prune | Execute durable CAG/cache adapter commands from caller-owned JSON payload files and retain request/output/evidence artifacts, including the Memory-owned verified-answer-cache-write contract used by live /ai closeout | | ntk runtime memory-record-write/read/promote/prune | Execute reusable Memory OS record adapter commands from caller-owned JSON payload files and retain request/output/evidence artifacts | | ntk runtime memory-local-write/read/prune | Execute operational-memory adapter commands from caller-owned JSON payload files and retain request/output/evidence artifacts | | ntk runtime memory-vault-materialize | Execute grouped vault materialization through the external memory boundary from a caller-owned JSON payload file | | ntk runtime decision-memory-context | Read an OrchestrationRequest, execute the planned context package when required, and return AI injection env hints without raw context text | | ntk runtime prune-agent-runs | Prune managed agent-run artifacts with opt-in provider-store coordination via --include-provider-stores; default mode leaves provider stores and credentials untouched, routes sibling cleanup commands as recommendations, and emits redacted audit evidence | | ntk runtime prune-local-memory | Prune retained event, session, and artifact rows from the repository-owned SQLite local memory snapshot | | ntk runtime export-planning-summary | Export a context handoff summary from active planning artifacts, with an optional typed JSON control schema for automation consumers | | ntk runtime capture-change-evidence | Capture or refresh the repository-owned AI change-evidence artifact, inferring touched paths from git and writing deterministic JSON plus Markdown summary outputs with an optional typed JSON control schema | | ntk runtime super-agent-housekeeping | Run the native Super Agent housekeeping flow for one workspace, with an optional typed JSON control schema that preserves continuity refresh, retained cleanup-step execution, throttle state, and record-only output | | ntk runtime new-super-agent-worktree | Create a deterministic Super Agent git worktree, with an optional typed JSON control schema that preserves slug derivation, branch-selection state, preview mode, and the exact managed git worktree add command | | ntk runtime export-enterprise-trends | Export enterprise validation and vulnerability trends | | ntk runtime evaluate-agent-pipeline | Evaluate the canonical agent pipeline manifests against the versioned eval fixture set, emit a typed JSON control schema, and persist the generated scorecard under .temp/agent-evals/ | | ntk runtime run-agent-pipeline | Execute the canonical agent pipeline against the authored stage graph, emit a typed JSON control schema, and persist managed run artifacts under .temp/agent-runs/ | | ntk runtime resume-agent-pipeline | Resume a managed agent pipeline from checkpoint state, emit a typed JSON control schema, and continue execution inside the native runtime boundary | | ntk runtime replay-agent-run | Replay a recorded agent-pipeline run directory into a typed JSON control schema and optionally persist the managed replay summary document | | ntk runtime apply-vscode-templates | Apply tracked VS Code template files into active workspace files, with an optional typed JSON control schema for automation consumers | | ntk runtime sync-vscode-global-settings | Render the tracked VS Code settings template into the global VS Code user profile, with an optional typed JSON control schema for automation consumers | | ntk runtime sync-workspace-settings | Synchronize one .code-workspace file from the repository-managed baseline, with an optional typed JSON control schema for automation consumers | | ntk runtime validate-vscode-global-alignment | Validate that the global VS Code user profile still contains the repository-managed settings, MCP, and snippet subset, with human-readable output or a typed JSON control schema for automation consumers | | ntk runtime sync-vscode-global-snippets | Synchronize tracked VS Code snippet templates into the global VS Code user profile, with an optional typed JSON control schema for automation consumers | | ntk runtime sync-vscode-global-mcp | Render the canonical MCP runtime catalog into the global VS Code user profile, with an optional typed JSON control schema for automation consumers | | ntk runtime sync-claude-settings | Merge the repository-managed Claude settings into the global Claude runtime, with an optional typed JSON control schema for automation consumers | | ntk runtime sync-claude-skills | Synchronize repository-managed Claude skills into the global Claude runtime, with an optional typed JSON control schema for automation consumers | | ntk runtime sync-codex-runtime-preferences | Apply repository-managed reasoning-effort and multi-agent safety defaults into the local Codex config.toml, with an optional typed JSON control schema for automation consumers | | ntk runtime render-vscode-mcp-template | Render the tracked VS Code MCP template from the canonical catalog | | ntk runtime render-provider-surfaces | Render tracked provider surfaces from the canonical projection catalog | | ntk runtime render-mcp-runtime-artifacts | Render the tracked VS Code and Codex MCP artifacts from the canonical catalog | | ntk runtime sync-codex-mcp-config | Apply MCP server definitions into the local Codex config.toml, preserving already-materialized ${input:...} auth values when the existing server section is otherwise canonically aligned and accepting fresh --mcp-input ID=VALUE overrides to rematerialize prompt-backed auth safely | | ntk runtime trim-trailing-blank-lines | Trim trailing whitespace and blank lines from text files | | ntk runtime pre-commit-eof-hygiene | Apply staged-file EOF hygiene for repository pre-commit flows | | ntk runtime setup-git-hooks | Configure repository-local or managed-global Git hooks directly through the native runtime boundary | | ntk runtime setup-global-git-aliases | Configure managed global Git aliases directly through the native runtime boundary | | ntk automation <runtime-command> | Visible transitional alias for the runtime command surface while automation pillar routing is completed; ntk runtime ... remains supported |

Validation Commands

| Command | Description | | --- | --- | | ntk validation all | Run the full validation orchestration for one profile, with an optional typed JSON control schema for automation consumers; shared profiles now include validate-command-surface-evidence, and release-facing profiles also include validate-ai-change-evidence | | ntk validation agent-orchestration | Validate multi-agent orchestration contracts and runtime assets | | ntk validation agent-permissions | Validate agent permission matrix and stage command contracts | | ntk validation agent-skill-alignment | Validate agent skill references against manifests, pipeline, and evals | | ntk validation agent-hooks | Validate repository-owned VS Code/Codex hook assets | | ntk validation audit-ledger | Validate the audit ledger hash chain, with an optional typed JSON control schema for automation consumers | | ntk validation ai-change-evidence | Validate the repository-owned AI change-evidence artifact, review/readiness semantics, and required-versus-executed validation coverage, with an optional typed JSON control schema for automation consumers | | ntk validation command-surface-evidence | Validate deterministic .build/evidence/command-surface/** coverage for the required operator-facing command families and scenarios, with an optional typed JSON control schema for automation consumers | | ntk validation authoritative-source-policy | Validate the centralized authoritative documentation policy and source map, with an optional typed JSON control schema for automation consumers | | ntk validation architecture-boundaries | Validate repository architecture boundary baselines, with an optional typed JSON control schema for automation consumers | | ntk validation instruction-architecture | Validate instruction architecture ownership and boundary rules, with an optional typed JSON control schema for automation consumers | | ntk validation instructions | Validate repository instruction and authored guidance assets, with an optional typed JSON control schema for automation consumers | | ntk validation instruction-metadata | Validate instruction, prompt, and chat mode frontmatter metadata, with an optional typed JSON control schema for automation consumers | | ntk validation compatibility-lifecycle-policy | Validate COMPATIBILITY.md lifecycle and EOL semantics, with an optional typed JSON control schema for automation consumers | | ntk validation dotnet-standards | Validate .NET template standards under .github/templates | | ntk validation policy | Validate repository policy contracts under .github/policies, with an optional typed JSON control schema for automation consumers | | ntk validation planning-structure | Validate versioned planning workspace structure, with an optional typed JSON control schema for automation consumers | | ntk validation powershell-standards | Validate PowerShell script standards across repository scripts, with an optional typed JSON control schema for automation consumers | | ntk validation readme-standards | Validate README files against repository standards, with an optional typed JSON control schema for automation consumers | | ntk validation rust-api-documentation | Validate public Rust API rustdoc summaries plus deterministic # Arguments coverage, with an optional typed JSON control schema for automation consumers | | ntk validation routing-coverage | Validate routing catalog coverage against golden fixtures, with an optional typed JSON control schema for automation consumers | | ntk validation runtime-script-tests | Validate native runtime smoke checks for the repository-owned runtime path, with mode-aware output that distinguishes native smoke from explicit target-repository script interoperability when required, plus an optional typed JSON control schema for automation consumers | | ntk validation security-baseline | Validate repository security baseline contracts, with an optional typed JSON control schema for automation consumers | | ntk validation shared-script-checksums | Validate shared script checksum manifest integrity, with an optional typed JSON control schema for automation consumers | | ntk validation shell-hooks | Validate shell hook syntax and semantic guards, with an optional typed JSON control schema for automation consumers | | ntk validation supply-chain | Validate local supply-chain baseline and export SBOM evidence, with an optional typed JSON control schema for automation consumers | | ntk validation template-standards | Validate shared repository template standards | | ntk validation release-governance | Validate release governance contracts and release guardrails, with an optional typed JSON control schema for automation consumers | | ntk validation release-provenance | Validate release provenance evidence and git traceability, with an optional typed JSON control schema for automation consumers | | ntk validation warning-baseline | Validate analyzer warning volume against the warning baseline, with an optional typed JSON control schema for automation consumers | | ntk validation workspace-efficiency | Validate VS Code workspace efficiency and configuration hygiene, with an optional typed JSON control schema for automation consumers |

Global Flags

| Flag | Description | | --- | --- | | --log-level <level> | Set logging level: off, error, warn, info, debug, trace | | --config <path> | Point the CLI at an explicit configuration file | | -v, --verbose | Enable verbose output | | -V, --version | Print version |

Architecture

The diagram below is a target boundary map rather than a literal Cargo dependency graph. It shows the simplified service pillars, shared support layers, and the app composition root the repository is converging toward.

flowchart TD
    APP["app<br/>(entrypoint + help)"]
    SHARED["shared<br/>(contracts + telemetry + tasking)"]
    UI["ui<br/>(cli + terminal)"]
    AUTO["automation"]
    CONTROL["control"]
    MEMORY["memory"]

    subgraph AUTOMATION_GROUP["automation"]
        CODEGEN["codegen"]
        VALIDATION["validation"]
        MANIFEST["manifest"]
        TEMPLATING["templating"]
    end

    subgraph CONTROL_GROUP["control"]
        ORCH["orchestrator"]
        WORKER["worker"]
    end

    subgraph MEMORY_GROUP["memory"]
        ENGINE["engine"]
    end

    APP --> UI
    APP --> SHARED
    APP --> AUTO
    APP --> CONTROL
    APP --> MEMORY

    UI --> SHARED
    AUTO --> SHARED
    CONTROL --> SHARED
    MEMORY --> SHARED

    AUTO --> CODEGEN
    AUTO --> VALIDATION
    AUTO --> MANIFEST
    AUTO --> TEMPLATING

    CONTROL --> ORCH
    CONTROL --> WORKER

    MEMORY --> ENGINE

    classDef entrypoint fill:#1f2937,stroke:#60a5fa,stroke-width:2px,color:#f8fafc
    classDef automation fill:#1f2937,stroke:#f59e0b,stroke-width:2px,color:#f8fafc
    classDef control fill:#1f2937,stroke:#4ade80,stroke-width:2px,color:#f8fafc
    classDef memory fill:#1f2937,stroke:#38bdf8,stroke-width:2px,color:#f8fafc
    classDef support fill:#1f2937,stroke:#a78bfa,stroke-width:2px,color:#f8fafc
    classDef interface fill:#1f2937,stroke:#fb7185,stroke-width:2px,color:#f8fafc
    classDef leaf fill:#111827,stroke:#9ca3af,stroke-width:1.5px,color:#f8fafc

    class APP entrypoint
    class AUTO automation
    class CONTROL control
    class MEMORY memory
    class SHARED support
    class UI interface
    class CODEGEN,VALIDATION,MANIFEST,TEMPLATING,ORCH,WORKER,ENGINE leaf

    style AUTOMATION_GROUP fill:#374151,stroke:#6b7280,stroke-width:1px,color:#f8fafc
    style CONTROL_GROUP fill:#374151,stroke:#6b7280,stroke-width:1px,color:#f8fafc
    style MEMORY_GROUP fill:#374151,stroke:#6b7280,stroke-width:1px,color:#f8fafc

• Blue marks the composition root.
• Amber marks deterministic engineering automation.
• Green marks orchestration and execution control.
• Cyan marks memory and retrieval.
• Purple marks shared support.
• Rose marks shared UI.

Current-repo note:

• the physical crate tree still uses historical names such as commands, core, knowledge, otel, and ui
• the target architecture above is the simplification direction now frozen in active planning

Agentic Surfaces

This workspace separates agentic capabilities by responsibility so each technology has a clear maintenance boundary.

| Surface | Role | Current repo entry points | Status | | --- | --- | --- | --- | | MCP | Tool projection, runtime configuration, lifecycle classification, explicit transport descriptors, explicit auth/session descriptors, a dedicated authored review-assessment boundary for MCP diagnostics that emits typed review categories plus reason codes, and runtime diagnostics for Codex and editor surfaces, with architecture-boundary enforcement against local recall and CAG helpers across both sync and diagnostics modules | .github/, .codex/, crates/control/runtime/src/sync/mcp_catalog.rs, crates/control/runtime/src/sync/mcp_config.rs, crates/control/runtime/src/sync/mcp_runtime_artifacts.rs, crates/control/runtime/src/diagnostics/doctor.rs, crates/control/runtime/src/diagnostics/mcp_review.rs | Supported | | A2A | Agent-to-agent interoperability and horizontal task delegation | Planning only; no dedicated runtime surface yet | Planned | | RAG | Repo-local lexical recall for instructions, plans, and source context | crates/core/src/local-context/ | Supported | | CAG | Context-augmented generation, context admission, request assembly, compaction, and token-budget aware prompting | crates/core/src/ai_context.rs, crates/control/orchestrator/src/execution/ai/request_context.rs, crates/control/orchestrator/src/execution/ai/token_economy.rs, crates/control/orchestrator/src/execution/ai/usage.rs, crates/control/runtime/src/hooks/super_agent_housekeeping.rs | Supported |

MCP owns tool and provider projection plus explicit authored transport and auth/session metadata, RAG owns deterministic lexical recall, CAG owns prompt shaping and budget-aware context assembly, and A2A remains the future boundary for agent-to-agent interoperability. Graph RAG is tracked separately in the knowledge-orchestrator workstream and is not the current implementation of crates/core/src/local-context/. The vault-materialization lane is routed through ntk-memory vault-materialize via adapter planning, keeping grouped knowledge-record frontmatter artifacts owned by the external memory service rather than an ad hoc Markdown note shape.

Internal Multi-Agent Runtime

Internal delegation is governed separately from A2A so leader-worker orchestration stays explicit and auditable.

| Element | Role | Canonical entry point | | --- | --- | --- | | Runtime contract | Freezes leader/worker roles, lifecycle states, lineage fields, inheritance rules, and mailbox vs approval-bridge coordination | definitions/templates/manifests/multi-agent-runtime.contract.json | | Architecture guidance | Human-readable model for delegation, lineage, approval bridges, and A2A separation | docs/knowledge-base/architecture/internal-multi-agent-runtime-model.md | | Sample contract | Trimmed example for docs, onboarding, and future validator fixtures | docs/samples/manifests/multi-agent-runtime.contract.sample.json |

This internal runtime may consume MCP, RAG, and CAG services, but it does not redefine them, and it must not be documented as A2A until a real interoperability protocol surface