SectionSource Local CLI Implementation Spec

Simple Summary

Phase 1E implements the local CLI command for body-free SectionSource v0 metadata.

This phase adds the local CLI command only. It does not add MCP, hosted MCP, Hub routes, search, persistence, Scooling runtime behavior, section bodies, snippets, summaries, PageIndex, OCR, LLM calls, or provider routing.

Technical Summary

The local CLI command exposes the existing readSectionSource behavior through a single note-scoped, JSON-only command. The command follows the existing get-note-outline, get-document-tree, and get-metadata-facets CLI pattern:

• load local config
• require --json
• accept exactly one vault-relative note path
• call resolveVaultRelativePath
• read one note through the existing local note-read path
• return body-free SectionSource v0 metadata
• exit non-zero for missing notes, traversal paths, invalid options, or non-JSON requests

Proposed Command

knowtation get-section-source <path> --json

The command is registered only in the local CLI.

Accepted Output

The command returns exactly the existing body-free SectionSource v0 shape:

{
  "schema": "knowtation.section_source/v0",
  "path": "inbox/example.md",
  "title": "Example",
  "sections": [
    {
      "section_id": "inbox-example-md:h1-example-0001",
      "heading_id": "h1-example-0001",
      "level": 1,
      "heading_path": ["Example"],
      "heading_text": "Example",
      "child_section_ids": [],
      "body_available": true,
      "body_returned": false,
      "snippet_returned": false
    }
  ],
  "truncated": false
}

Explicitly Excluded Output

The command must not output:

• note body text
• section body text
• snippets
• source excerpts
• full frontmatter
• absolute filesystem paths
• exact line ranges
• byte offsets
• section body lengths
• summaries
• vector scores
• provider payloads
• MCP resource URIs
• search results
• persistence ids
• Scooling adapter state

Error Behavior

The command must:

• fail when --json is omitted
• fail when the note path is missing
• fail when more than one note path is supplied
• fail for traversal paths before note reads
• fail for missing notes using the same local note-read behavior as get-note-outline
• use existing CLI error handling and JSON error behavior
• not include note body text, snippets, full frontmatter, or absolute paths in errors

Authorization And Path Safety

The command preserves the local note-read authorization boundary:

• the caller may only read notes available through the configured local vault
• paths must be vault-relative
• absolute paths are rejected
• traversal paths are rejected before note reads
• symlinks that escape the vault remain blocked by existing vault behavior

Transport Boundaries

Phase 1E accepts only the local CLI implementation.

It does not approve:

• self-hosted MCP
• hosted MCP
• Hub REST
• OpenAPI
• Hub UI
• canister routes
• search
• persistence or sidecars
• Scooling runtime consumption
• section bodies
• snippets
• summaries
• PageIndex
• OCR
• LLM calls
• external provider routing

Seven-Tier Test Requirements

Unit

• The command name and required --json behavior are documented.
• The output field allowlist matches SectionSource v0.
• body_returned and snippet_returned remain false.

Integration

• The command uses the existing config, path validation, and note-read behavior.
• Missing and traversal paths fail consistently with adjacent body-free CLI commands.
• The command output matches readSectionSource for the same note.

End To End

• A user can request one note's body-free section candidates through the CLI.
• No CLI flow returns section body text or snippets.
• Non-JSON usage fails rather than printing an informal body-bearing view.

Stress

• Large notes remain capped by heading count and input caps.
• Large outputs remain bounded by section count and text caps.
• Repeated calls are deterministic for unchanged notes.

Data Integrity

• The command does not write notes, sidecars, indexes, vectors, memory, summaries, or canister state.
• The command reflects current note content only.
• No cached section record is created.

Performance

• The command reads one note only.
• The command does not scan the whole vault.
• The command does not call external providers.

Security

• No note body text appears in output.
• No section body text appears in output.
• No snippets appear in output.
• No full frontmatter appears in output.
• No absolute filesystem paths appear in output.
• No MCP resource URI appears in output.
• Prompt-injection text remains untrusted source material.
• Hosted, Scooling, classroom, search, and persistence exposure remain blocked.

Stop Conditions

Stop and re-plan if implementation requires:

• returning note body text
• returning section body text
• returning snippets
• returning exact line ranges
• returning byte offsets
• returning section body lengths
• adding summaries
• adding search, vectors, indexes, persistence, sidecars, or memory events
• adding MCP, hosted MCP, Hub REST, OpenAPI, Hub UI, canister routes, or Scooling runtime code
• sending note-derived content to LLMs, OCR, PageIndex, or external providers
• weakening existing local note-read behavior

Acceptance Criteria

Phase 1E is accepted when:

• The local CLI registers the get-section-source command name.
• The command requires JSON-only output.
• The command limits output to body-free SectionSource v0 metadata.
• The command preserves local note-read path and authorization behavior.
• The command keeps MCP, hosted, Hub, search, persistence, Scooling, body, snippet, provider, OCR, PageIndex, and LLM behavior blocked.
• Tests prove no MCP, hosted, Hub, search, persistence, or Scooling runtime transport has been added.

Recommendation

The self-hosted MCP implementation is accepted in docs/SECTION-SOURCE-MCP-IMPLEMENTATION-SPEC.md and implemented in mcp/create-server.mjs.

Proceed next only with a separate hosted authorization review spec or Scooling adapter planning spec. Do not add hosted, Hub, search, persistence, Scooling, body reads, snippets, summaries, OCR, PageIndex, LLM calls, or provider routing without that separate plan.