This tool is the server-side source for Nogra workspace files. It does not write files and does not
    execute commands. The caller's Claude Code client should write each returned file into the user's chosen
    workspace path using the file writePolicy. Newer clients should use the returned installPlan
    for phase-grouped writes and a quieter installation summary.

    When to use:
    - Initialize Nogra in a customer workspace after the hosted MCP server has been added.
    - Respond to user requests such as "run Nogra init" or "/nogra init".
    - Retrieve the current public-safe Nogra workspace methodology bundle.
    - Use mode=plugin when the Nogra plugin is installed; plugin mode returns only workspace bootstrap files,
      not plugin-owned commands or skills.

    When NOT to use:
    - Do not treat this as an installer that can write to the user's filesystem.
    - Do not overwrite files marked ask_before_overwrite without asking the user.
    - Do not expect this to configure provider auth, run local commands, or perform workspace execution.

    Examples:
    >>> init(workspace_name="Acme App")
    {"schema": "nogra.init.bundle.v1", "releaseVersion": "v1.0.0", "status": "ready", "writeMode": "client_writes_files", "files": [...]}
    >>> init(workspace_name="Acme App", mode="plugin")
    {"schema": "nogra.init.bundle.v1", "releaseVersion": "v1.0.0", "initMode": "plugin", "files": [...]}
    

    Nogra execution roles are not installed as persistent Claude Code project agents. The Manager fetches a
    handoff contract at a dispatch or verification boundary, then spawns Claude Code's built-in general-purpose
    subagent with the returned prompt plus the approved brief, run id, scope and evidence contract.
    Manager must not implement the approved scope inline. If the client cannot spawn the subagent, stop and
    surface the missing primitive instead of offering a fallback.

    When to use:
    - After a brief is approved and a dispatch receipt/run id exists, fetch kind=executor before spawning the run agent.
    - Before independent evidence checks, fetch kind=verifier before spawning a disposable verifier agent.

    When NOT to use:
    - Do not call repeatedly during normal lifecycle logging.
    - Do not persist the returned prompt as a .claude/agents file.
    - Do not use this as execution approval; the user-approved brief and dispatch receipt remain the authority.
    - Do not use this to justify inline Manager execution.

    Examples:
    >>> handoff_contract("executor")
    {"schema": "nogra.handoff.contract.v1", "status": "ready", "kind": "executor", "targetSubagent": {"type": "general-purpose", ...}}
    

    This tool is download-on-demand. It does not write files, start local processes or change the workspace.
    The caller's Claude Code client should write returned files only after the user explicitly asks for the
    optional feature, preserving each returned writePolicy.

    When to use:
    - Install an optional Nogra feature advertised by init, such as the local pinboard renderer.
    - Re-download an optional feature file after the user asks to repair or update it.

    When NOT to use:
    - Do not call during default /nogra init unless the user opted into that feature.
    - Do not auto-start any local process after writing optional files.

    Examples:
    >>> optional_feature_bundle("local-pinboard-renderer")
    {"schema": "nogra.optional_feature.bundle.v1", "status": "ready", "files": [...]}
    

    Returns the public registry payload for the configured workspace, including public tool names, resource
    URIs, boundary flags, extension metadata, and the workspace substrate paths that a caller may inspect.

    When to use:
    - Discover what the public Nogra MCP exposes before choosing another tool.
    - Check whether extensions are enabled and which tools/resources are visible in this workspace.

    When NOT to use:
    - Do not use this to read the contents of resources; fetch the resource URI directly instead.
    - Do not use this to create provider handoff receipts, post events, or update runs.

    Examples:
    >>> registry()
    {"name": "nogra-mcp", "version": "v1.0.0", "status": "v1-local-validation", "tools": [...], ...}
    

    Returns the fields, markdown anchors, default return policy and public resources needed to draft a
    `nogra.brief.v1` brief before calling validation or save tools.

    When to use:
    - Draft a Nogra brief from user intent without guessing field names or required sections.
    - Check how markdown sections map into the structured brief object.
    - Confirm that response length policy is a return policy, not a brief length cap.

    When NOT to use:
    - Do not use this as execution approval.
    - Do not dispatch work from this contract alone; save/promote/dispatch gates still apply.

    Examples:
    >>> brief_contract(workspace_id="acme-app")
    {"schema": "nogra.brief.contract.v1", "briefSchema": "nogra.brief.v1", "requiredFields": [...]}
    

    Renders the configured provider handoff template, redacts secret-shaped text, stores the
    hosted receipt, and returns the handoff id plus localWrites guidance for the caller-owned
    `.nogra/` receipt copy.
    This public V1 tool does not call a live provider.

    When to use:
    - Prepare a redacted provider handoff before handing work to another model or reviewer.
    - Validate how a prompt, context, and mode will render without making an external model call.

    When NOT to use:
    - Do not use this when you need an actual provider response; providerCall.attempted is always false.
    - Do not use this for run tracking or pinboard activity; use event/run tools for that.

    Examples:
    >>> provider_handoff(provider="codex", prompt="Review this brief", context="Scope: docs only", intent="review")
    {"status": "dry_run", "handoffId": "provider-handoff-...", "provider": "codex", "intent": "review", ...}
    

    Looks up a previously written provider handoff receipt by id, validates the id shape, reads the receipt JSON from the
    workspace .nogra receipts directory, and returns the redacted rendered prompt plus any redaction labels.

    When to use:
    - Inspect the exact redacted prompt that was stored for a previous dry-run provider handoff.
    - Recover prompt text by handoff id without re-rendering or creating a new receipt.

    When NOT to use:
    - Do not use this before creating a provider handoff receipt; missing ids return a missing status.
    - Do not use this for unredacted secrets or raw provider prompts; the stored field is redacted.

    Examples:
    >>> provider_handoff_read("provider-handoff-20260504120000-abc123ef")
    {"status": "ok", "handoffId": "provider-handoff-20260504120000-abc123ef", "renderedPromptRedacted": "...", "redactions": []}
    

    Applies the public Nogra secret-pattern filter to caller-provided text and returns the redacted text plus
    category labels for every detected secret-shaped match.

    When to use:
    - Preview which secret-pattern labels Nogra would detect in text before writing it to workspace substrate.
    - Build caller-side masking or display logic from the same labels used by write-time annotations.

    When NOT to use:
    - Do not use this as destructive storage; write-tools annotate records and keep original text.
    - Do not use this for provider handoff receipts; provider_handoff already redacts rendered prompts.

    Examples:
    >>> redact_text("token=sk_test_abcdefghij1234567890")
    {"redacted": "token=[REDACTED]", "redactions": ["api-key-shape"]}
    

    Writes one JSONL event into the configured workspace .nogra events log with schema, id, timestamp,
    workspace id, event type, message, and optional brief/run links, then returns the event id and events
    resource URI.

    When to use:
    - Record a visible workspace activity note for pinboard or workflow surfaces.
    - Attach a lightweight event to a brief id, run id, or both.

    When NOT to use:
    - Do not use this for run status history; use update_run for run updates.
    - Do not use this to store large reports or artifacts; it appends a compact event message.

    Examples:
    >>> post_event("dispatch", "Queued analytics audit", brief_id="brief-123", run_id="run-456")
    {"status": "ok", "eventId": "event-...", "resourceUri": "nogra://workspace/local/pinboard/events"}
    

    Returns recent JSONL event entries from the configured workspace .nogra events log.

    When to use:
    - Inspect recent public workspace activity recorded through post_event.
    - Build caller-driven views over the local event substrate without reading resources directly.

    When NOT to use:
    - Do not use this for run status history; use recent_runs for run updates.
    - Do not use this to append events; use post_event for writes.

    Examples:
    >>> recent_events(limit=20)
    {"workspaceId": "local", "events": [...]}
    

    Writes one JSONL status entry under the configured workspace .nogra runs directory for the sanitized run id,
    including schema, timestamp, workspace id, status, notes, and optional brief id, then returns the run resource
    URI.

    When to use:
    - Record that a run moved to a new status such as queued, running, complete, blocked, or failed.
    - Attach notes to a run timeline without changing any external transport state.

    When NOT to use:
    - Do not use this for general activity notes; use post_event for non-run events.
    - Do not use this to dispatch work or submit report artifacts; this only appends a public run update.

    Examples:
    >>> update_run("run-456", "running", notes="Audit started", brief_id="brief-123")
    {"status": "ok", "runId": "run-456", "resourceUri": "nogra://workspace/local/runs/run-456"}
    

    Returns the latest valid JSONL update from recent run files under the configured workspace .nogra runs
    directory, including run id, status, timestamp, brief id, and notes.

    When to use:
    - Inspect recent run status updates recorded through update_run.
    - Build caller-driven views over the local run substrate without reading resources directly.

    When NOT to use:
    - Do not use this to append run status; use update_run for writes.
    - Do not use this for general activity events; use recent_events for event history.

    Examples:
    >>> recent_runs(limit=10)
    {"workspaceId": "local", "runs": [...]}
    

    Parses markdown or structured input, normalizes it to the public brief schema, validates it, and returns
    localWrites for the caller-owned `.nogra/` draft store. In hosted mode, this tool does not rely on persistent
    server-side draft storage.

    When to use:
    - Create or update a caller-owned brief draft through the MCP tool interface.
    - Convert a markdown brief into public structured brief JSON before promotion.

    When NOT to use:
    - Do not use this to mark a brief ready; use brief_promote for promotion.
    - Do not use this for run updates or events; use the run/event tools for those substrates.

    Examples:
    >>> brief_save({"title": "Import audit", ...}, source="cli")
    {"schema": "nogra.brief.v1", "releaseVersion": "v1.0.0", "briefId": "brief-...", "status": "draft", "path": ".nogra/briefs/drafts/brief-....json", ...}
    

    Parses and normalizes the supplied payload, then runs the public brief schema checks. Invalid input is returned
    as structured errors rather than raised to the caller.

    When to use:
    - Check whether a draft can be saved or promoted before writing it.
    - Inspect the normalized public brief shape produced from markdown.

    When NOT to use:
    - Do not use this to persist a draft; use brief_save for writes.
    - Do not use this to read stored briefs; use brief_read or recent_briefs.

    Examples:
    >>> brief_validate({"title": "Import audit", ...})
    {"valid": true, "errors": [], "normalized": {...}}
    

    Marks a draft ready, validates it, renders markdown, and returns localWrites for the promoted brief artifact.
    Hosted/plugin mode should pass the inline brief payload because the customer's local `.nogra/` store is the
    authority.

    When to use:
    - Convert a valid draft payload into a ready markdown brief artifact.
    - Produce a stable promoted brief path while keeping draft JSON readable.

    When NOT to use:
    - In hosted/plugin mode, do not rely on server-side draft state; pass the local draft payload inline.
    - Do not use this to edit a draft; use brief_save for updates.

    Examples:
    >>> brief_promote("brief-import-audit-2026-05-06-a1b2c3", payload={...})
    {"draft": {...}, "brief": {...}, "path": ".nogra/briefs/BRIEF-import-audit-2026-05-06.md"}
    

    Reads draft JSON first and falls back to matching promoted markdown when no draft exists.

    When to use:
    - Retrieve a saved or promoted public brief through tools.
    - Verify the current status and path for a known brief id.

    When NOT to use:
    - Do not use this to list recent briefs; use recent_briefs.
    - Do not use this to validate arbitrary unsaved input; use brief_validate.

    Examples:
    >>> brief_read("brief-import-audit-2026-05-06-a1b2c3")
    {"status": "ok", "brief": {...}, "path": ".nogra/briefs/BRIEF-import-audit-2026-05-06.md"}
    

    Returns recent draft JSON and promoted markdown briefs from the configured workspace brief substrate.

    When to use:
    - Build caller-driven brief lists through tools.
    - Inspect recent draft and promoted brief activity without reading resource URIs.

    When NOT to use:
    - Do not use this to read a specific brief body; use brief_read.
    - Do not use this to create or promote briefs; use the write lifecycle tools.

    Examples:
    >>> recent_briefs(limit=10)
    {"workspaceId": "local", "briefs": [...]}
    

    Creates a state-only run record, allocates report/output/log artifact paths under the workspace transport
    substrate, persists state atomically, and appends a transport event.

    When to use:
    - Start tracking caller-owned work through public transport state.
    - Allocate artifact paths before an external runtime begins work.

    When NOT to use:
    - Do not use this to execute work; public transport is state-only.
    - Do not use this for lightweight event logging; use post_event for that.

    Examples:
    >>> transport_register("import-audit", brief_id="brief-123")
    {"schema": "nogra.transport.run.v1", "runId": "transport-...", "status": "queued", ...}
    

    Applies partial status, phase, notes, error, or summary updates to an existing run and appends an event with
    the changed fields.

    When to use:
    - Move a run from queued to running, returned, failed, or another public lifecycle state.
    - Attach status notes from an external runtime.

    When NOT to use:
    - Do not use this to write report artifacts; use transport_submit_report.
    - Do not use this for brief draft lifecycle changes.

    Examples:
    >>> transport_update("transport-20260506120000-a1b2c3d4", status="running")
    {"runId": "transport-...", "status": "running", "phase": "running", ...}
    

    Use when the user stops an executor, cancels a run, or a dispatched run
    must be marked cancelled without pretending verification completed.

    In hosted/plugin mode the customer's `.nogra/` ledger is local. Pass
    current_run when available so this tool can return exact localWrites for
    the run record and cancellation event.
    

    Bundles an existing public brief, caller-defined target, optional linkage, optional doctrine text, and metadata
    into a self-contained handoff for a caller-owned runtime. In plugin mode, this handoff is material for
    a customer-side ephemeral subagent; it is not permission for Manager to execute the scope inline.

    When to use:
    - Prepare a saved public brief for handoff to a runtime without requiring another MCP read.
    - Include small workspace-local reference files beside the embedded brief content.
    - Support a plugin-mode Manager -> ephemeral executor crossing when dispatch handoff material is useful.

    When NOT to use:
    - Do not use this to execute work; it only builds a handoff.
    - Do not use this without a saved brief; use transport_register directly for brief-less tracking.
    - Do not use this as a fallback after subagent spawning fails.

    Examples:
    >>> dispatch_handoff("brief-import-audit-2026-05-06-a1b2c3", "audit-job")
    {"schema": "nogra.dispatch.handoff.v1", "target": "audit-job", "brief": {...}, ...}