Summary

The repository MCP tools advertise subdirectory as an optional source subdirectory for repository_attach, repository_create, and repository_update, but using it while attaching a new local Git checkout with an unborn branch failed with an image-side Iceberg API error.

This was confusing from an agent workflow perspective because the schema made subdirectory: "src" look valid, but the failure only appeared after the write call crossed into Iceberg.

Reproduction

In a running Pharo 13 image with packages already loaded:

• BaselineOfSlim
• Slim-Core
• Slim-Tests

Create a new local Git checkout at:

/Users/gabriel.darbord/dev-nexus/sources/pharo-slim

Then call:

{
  "toolName": "repository_attach",
  "arguments": {
    "name": "pharo-slim",
    "location": "/Users/gabriel.darbord/dev-nexus/sources/pharo-slim",
    "subdirectory": "src",
    "packageNames": ["BaselineOfSlim", "Slim-Core", "Slim-Tests"]
  }
}

Observed behavior

repository_attach failed with an Iceberg message-not-understood error around IceUnbornProject >> #sourceDirectory:.

Retrying without subdirectory succeeded:

{
  "toolName": "repository_attach",
  "arguments": {
    "name": "pharo-slim",
    "location": "/Users/gabriel.darbord/dev-nexus/sources/pharo-slim",
    "packageNames": ["BaselineOfSlim", "Slim-Core", "Slim-Tests"]
  }
}

Then trying to set the subdirectory after attach also failed:

{
  "toolName": "repository_update",
  "arguments": {
    "repositoryName": "pharo-slim",
    "location": "/Users/gabriel.darbord/dev-nexus/sources/pharo-slim",
    "subdirectory": "src",
    "packageNames": ["BaselineOfSlim", "Slim-Core", "Slim-Tests"]
  }
}

The update result reported:

Failed to update repository: Message not understood: IceUnbornProject >> #sourceDirectory:

Expected behavior

One of these would make the tool easier for agents to use correctly:

1. Support setting subdirectory on an unborn repository, if Iceberg has a safe way to do that.
2. Reject subdirectory before mutating when the selected repository is unborn, with an actionable error such as: subdirectory is not supported until the repository has an initial head; attach without subdirectory, commit/adopt head, then update.
3. Document the limitation in the tool description/schema for repository_attach, repository_create, and repository_update.

Why this matters

Agent callers inspect schemas and often trust optional fields as supported in the current repository state. A state-specific validation error or clearer description would prevent unnecessary retries and avoid exporting packages to the repository root when the intended layout is src/.