MCP surface narrower than the CLI: unlink rejects brownfield relations, ingest refuses a directory source

[explosivebit]

Two places where the MCP surface is narrower than the CLI for the same operation. Both are
schema/validation choices, so an agent driven over MCP cannot do what the CLI documents.

1. forgeplan_unlink (MCP) rejects the brownfield relation set

crates/forgeplan-mcp/src/server.rs:1276 defines the accepted argument set as exactly five
variants:

enum RelationKind { Informs, BasedOn, Supersedes, Contradicts, Refines }

The core recognizes two more names as coverage relations - crates/forgeplan-core/src/brownfield.rs:493:

"informs" | "based_on" | "refines" | "demonstrates" | "covers"

The CLI reaches core's wider set (its relation argument is normalized by
link::normalize_relation, crates/forgeplan-cli/src/commands/link.rs:14), so demonstrates and
covers round-trip on the CLI but are rejected at the MCP schema layer as an invalid enum value -
a schema rejection, not a domain error, which makes it look like a bad request rather than an
unsupported relation.

2. forgeplan_ingest (MCP) refuses a directory source; the CLI walks it

phase5_validate_path (crates/forgeplan-mcp/src/server.rs:10398-10405) requires a regular file:

if !canon.is_file() { return Err("path is not a regular file"); }

The CLI's ingest walks directories - crates/forgeplan-cli/src/commands/ingest.rs:355-362
descends into ft.is_dir() entries and collects files. So the same command with a directory source
works from the shell and fails over MCP.

Why it matters

Agent-facing surfaces are where these get hit: an orchestrator that learned a workflow from the CLI
docs writes the same call over MCP and gets a rejection it cannot interpret from the message.

Fix

Either widen the MCP argument types to match core/CLI, or document the narrower contract on the MCP
tool descriptions. Deciding which takes an owner's call: widening changes a security-adjacent
schema, documenting leaves two surfaces that differ.

Revisit trigger

Act if an MCP-driven run reports "invalid value" for a relation the CLI accepts, or if the ingest
engine's MCP surface is described in a release note as equivalent to the CLI's.

[explosivebit]

Sharper evidence after a second pass over the source (0.37.0). Both points are wider than first described.

1. Six relations are missing, not two

Core's canonical list is crates/forgeplan-core/src/link/mod.rs:97-110:

pub const VALID_RELATIONS: &[&str] = &[
    "informs", "based_on", "supersedes", "contradicts", "refines", "supports",
    // Audit-r7 M3: Epic #287 brownfield relations.
    "demonstrates", "covers", "triangulates", "references", "belongs_to",
];

11 entries. The MCP argument enum (crates/forgeplan-mcp/src/server.rs:1276) has 5. These six are
accepted end to end on the CLI - link::normalize_relation (crates/forgeplan-cli/src/commands/link.rs:14)
validates against VALID_RELATIONS - and rejected at the MCP schema layer:

supports, demonstrates, covers, triangulates, references, belongs_to

So website/src/content/docs/docs/mcp/forgeplan_unlink.md now lists the five the MCP surface takes
and says plainly that the CLI accepts more, rather than implying the two agree.

2. The ingest gap is "never reads the file", not "accepts an invalid one"

The handler comment says it outright (crates/forgeplan-mcp/src/server.rs, at forgeplan_ingest,
IngestParams above it):

// Wave 3 limitation: forgeplan-core does not currently re-export
// `serde_yaml::from_str::<Mapping>` and the MCP crate cannot add
// a new top-level dep in this wave.

The MCP path canonicalises both paths (requiring regular files) and applies two byte-size guards,
then returns a planned envelope with drafts: []. It never calls serde_yaml::from_str and never
looks for a sources: key. The CLI does parse: crates/forgeplan-cli/src/commands/ingest.rs:160-180
(read_mapping_with_limits then serde_yaml::from_str), refusing an invalid mapping with
invalid mapping YAML and exit 2.

Precise statement for the record: the MCP surface accepts any regular file at the path without
reading its contents, so it cannot distinguish a valid SPEC-004 mapping from an invalid one. That is
a documented Wave 3 limitation, not a bug in the strict sense - which is exactly why it belongs on
the MCP page as a limitation rather than being papered over.

Where this is now documented

• website/src/content/docs/docs/cli/ingest.md and mcp/forgeplan_ingest.md state the CLI/MCP split
• website/src/content/docs/docs/mcp/forgeplan_unlink.md names the six relations the MCP surface
  does not take

The pages describe the divergence; whether to close it is the decision this issue asks for.