Skip to content

Document sources

Register an instruction document from an already linked project repository:

heyaira-admin add-document-source \
  --project-id <project-id> \
  --github-owner example \
  --github-repository instructions \
  --document-role instruction \
  --path AGENTS.md \
  --track main

Choose exactly one of --track <branch> and --commit-sha <40-character-SHA>. Tracking stores the branch name with a NULL commit; pinned registration keeps the existing immutable SHA behavior. Repeating registration for the same project, repository, role, path and branch updates the fragment limit, reactivates the source and returns its existing source_id. Avoid leaving both a pinned and a tracking registration active for the same instruction path: automatic dispatch rejects ambiguous mappings. Registration is a local administrator operation; it does not modify Git or deploy services.

Tracking instructions resolve only at workflow_send: the task repository uses the task's base commit, other project repositories use the named branch's HEAD. Worker, verifier and correction attempts use the frozen manifest for that workflow. Sending a new revision picks up a fresh HEAD. The explicit workflow_dispatch_catalog pin API does not accept arbitrary tracking commits. Direct git_document_get reads still require a pinned source; tracking-only sources have no standalone commit and return invalid_commit. See the workflow contract for manifest provenance and replay behavior.

Account instruction sources

After deployment of migration 057_account_instruction_sources.sql, a local administrator can bind the instruction repository to an account:

heyaira-admin link-account-repository \
  --account-id <account-id> \
  --github-owner h8v6 --github-repository heyaira \
  --repository-url https://github.com/h8v6/heyaira \
  --github-installation-id <installation-id>

heyaira-admin add-account-document-source \
  --account-id <account-id> \
  --github-owner h8v6 --github-repository heyaira \
  --path docs/agents/core/core.md --track main

Register the two mode paths the same way: docs/agents/core/modes/bridge-worker.md and docs/agents/core/modes/bridge-verifier.md. Both workflow_send and workflow_dispatch_catalog assemble these account layers automatically; callers do not supply account source pins. Tracking always uses branch HEAD, even when the task happens to use the same GitHub repository. A dispatch resolves a shared branch only once and freezes the resulting content and provenance. Core and mode are never truncated to a token budget.

For interactive onboarding with session_start, DevOps also registers these account paths using the same add-account-document-source ... --track main command (along with the shared docs/agents/core/core.md):

  • docs/agents/core/modes/local-coordinator.md
  • docs/agents/skills/README.md
  • docs/agents/skills/take-over-session/SKILL.md
  • docs/agents/skills/write-session-handoff/SKILL.md

session_start resolves each shared repository/branch HEAD once per invocation, then reads all configured documents at that commit. It returns ordered layers with content, SHA-256, character counts, estimated tokens and provenance; absent paths are reported in layers_missing. The two procedure entries share the procedures layer name. Configured read failures are errors, and total content over 60 KiB is rejected rather than truncated. Only local-coordinator is supported, for interactive project tokens and OAuth; execution tokens cannot use this tool. These registrations remain DevOps configuration, not worker operations or a deployment grant.

Account registration accepts only --document-role instruction (the default) and safe file paths under docs/agents/. Choose exactly one of --track and --commit-sha; --max-bytes defaults to 64000. Repeating the same account, repository, path and pin/branch updates the limit, reactivates the source, and returns its existing ID. Keep only one active source per layer path across the account: duplicate mappings fail dispatch.

heyaira-admin revoke-account-document-source \
  --account-id <account-id> --source-id <source-id>

There is no MCP write operation for these sources. Account bindings do not create project repository bindings, and account sources do not appear in runtime_bootstrap_get or become readable through git_document_get. Without configured account sources, dispatch remains compatible and reports catalog.layers_missing=["core","mode"]. A configured source on a revoked repository fails dispatch; revoking a source invalidates an already resolved catalog at validation. These commands are configuration operations for DevOps after deployment, not part of the worker task or a deployment grant.