Skip to content

Agent Contract

The Agent Contract is a versioned, inspectable discovery layer. It keeps AI clients from guessing configuration fields, CLI syntax, MCP permissions, or deployed site routes.

Installed package contract

For creating or maintaining a local project, start at:

text
@aicode-nexus/silen/agent/manifest.json

The package manifest points to the exact version’s configuration API, CLI and MCP contracts, public TypeScript exports, guide, and task playbooks. For example, agent/tasks/create-site.md describes the supported activation path and links back to authoritative machine-readable resources rather than copying their definitions.

Deployed site contract

Each enabled production build publishes a site-specific entry point at /.well-known/silen/manifest.json, resolved under base. This official site’s live contract is the Silen manifest. The manifest schema has no deployment origin field. It describes the base, language, resources, tasks, and public project guidance. Resource and task URLs remain base-relative.

ts
ai: {
  contract: {
    enabled: true,
    instructions: '.silen/ai-public.md',
    tasksDir: '.silen/ai-tasks',
  },
}

Instructions and tasks are explicit public build input. Do not include local absolute paths, secrets, private endpoints, credentials, or unpublished operating details.

Schema version 2

The current manifest and API documents use schemaVersion: 2. The manifest's MCP capability declares stdio, protocol versions 2025-11-25 and 2026-07-28, an empty extension list, local-only operation, read-only default, and the --allow-write gate. The API document adds an outputSchema for every tool. Successful MCP calls expose the corresponding schema-validated structuredContent alongside text.

This contract does not advertise remote transport or optional MCP extensions. Those capabilities require separate designs and authorization.

The package also contains the generated filesystem Skill at dist/agent/skills/silen-docs-readonly, and the CLI API records silen ai skills plus --experimental-skills-over-mcp. The default manifest still says extensions: [] because an optional runtime flag is not a site capability. Skill text is procedural knowledge: it does not grant a host permission to run commands, use the network, write files, commit, push, or deploy.

Client behavior

Codex, Claude Code, Cursor, and other clients should consume the same manifest instead of keeping client-specific API copies. When a client does not support the declared contract schema, it must follow linked public Markdown and remain read-only. For deployed content, the site manifest is authoritative; for code generation against an installed package, the package contract is authoritative.

Continue with the local workspace and MCP.