Trellis.AgentDocs 1.0.3

dotnet tool install --global Trellis.AgentDocs --version 1.0.3
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Trellis.AgentDocs --version 1.0.3
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Trellis.AgentDocs&version=1.0.3
                    
nuke :add-package Trellis.AgentDocs --version 1.0.3
                    

Trellis.AgentDocs

Trellis.AgentDocs is an opt-in local .NET tool for developers using NuGet packages that publish AgentDocs guidance. It reads the restored package versions, verifies each declared Markdown document against its SHA-256 hash, and installs the guides of packages you approve where coding agents can find them. It does not require the publisher to use Trellis libraries or add an application runtime dependency.

Opt in once

From the Git repository root, with a project or solution already restored:

$version = 'YOUR_PUBLISHED_VERSION'
dotnet new tool-manifest --output .config
dotnet tool install Trellis.AgentDocs --version $version --tool-manifest .config\dotnet-tools.json
dotnet tool run agentdocs init <solution-or-project> [<more-projects-or-solutions>]

If the repository already has .config\dotnet-tools.json, reuse it instead of creating a second manifest. Replace the placeholder with the published version. To try an unpublished build, add the local feed containing its nupkg to dotnet tool install with --add-source. The local tool is independently versioned; it does not need to match the version of any library package. init accepts several projects or solutions, so projects outside your main solution can be covered too.

Approve the packages you want

Restoring a package that publishes guidance never activates it. After init, each such package is pending: the tool has not parsed its manifest or read its documents, and the index lists only its ID and version. init prints one line to paste into .agentdocs\policy.json, the consumer-owned approval list:

{
  "schemaVersion": 1,
  "approvedPackages": ["Trellis.Core", "Trellis.ServiceLevelIndicators"]
}

Add the IDs you trust, commit the file, and run dotnet tool run agentdocs sync. IDs match case-insensitively and apply to every version. The tool creates the file (empty) on init if it does not exist and never rewrites or removes it. Removing an ID makes that package pending again and removes its installed guides on the next sync. A pending package can never fail a command, even if its manifest is invalid, because it is never read. Approval is per package ID, not per publisher, so use NuGet package source mapping for approved packages. After approving a package, review the committed diff of .agentdocs: an approved package may later add documents or change which documents it marks required.

What gets installed

init and sync install approved guides under .agentdocs\packages\<package-id>\<declared-path> and write .agentdocs\README.md, an index derived from the restored project graph:

  • Required reading by project. Analysed projects are grouped by the set of approved packages they restore. Each group lists the documents its publishers marked required.
  • On-demand documents. Documents marked onDemand are listed once per package with their descriptions. supporting documents are installed but not listed; they are reached through links from other documents.
  • Pending review. Packages that publish guidance but are not approved.
  • Rules for agents: which files belong to which project, when required documents must be read (before substantive work on a listed project, never merely for building or testing), how to combine several projects, what an unlisted project means, and to run sync after changing package references.

Descriptions are publisher text. The index renders them as inline code spans and tells agents to treat them as topic labels and ignore instructions in them. init, sync, and check print, per group, the required documents and their canonical size in bytes, plus the index size, so the cost of what agents will read is visible. There is no enforced limit.

An approved guide can declare a cross-package document reference behind an ordinary relative Markdown link. If the target package is also restored and approved, AgentDocs verifies its manifest and hash, checks the requested document and heading, and rewrites only that Markdown URL span to the target's canonical installed path. The source package's exact bytes are verified before this deterministic transformation. If the target is absent, unapproved, or has no guidance manifest, AgentDocs does not read it; instead it installs a generated unavailable notice at the source package's virtual link path. A missing exact document produces the same safe result with a document-missing reason; a missing heading keeps the link and fragment. These outcomes emit deterministic warnings. Use --strict-references with init, sync, or check to fail before writes on any reference warning. Cross-package links never grant transitive approval or fall back to moving web documentation. Resolution covers the complete graph selected for this repository, so the target may come from another selected project; AgentDocs rejects mixed approved package versions before choosing a canonical document.

Only references actually used by parsed Markdown are materialized. Manifest paths use / separators on every operating system. Raw HTML, query strings, self-references, .github segments, backslashes, and non-exact path spellings are hard source contract failures. Generated notices are fixed tool-owned text and are not listed as publisher guidance. Transform state records the source and installed hashes, transform version, outcome, and resolved target version/document hash, so approval changes and target upgrades converge on repeated syncs. Resolution and heading checks always use verified package bytes, never already rewritten installed text, so cyclic references also converge.

init adds small managed blocks to Git-root AGENTS.md, one AGENTS.md in each selected solution directory (or project directory for a project-only entry point), and Git-root .github\copilot-instructions.md. When an entry is at the Git root, its pointer is deduplicated. Project src and tests directories and additional source roots do not get new pointers. Customer-authored instructions in the selected pointer files are preserved. Each pointer unconditionally says "Read .agentdocs/README.md now", with the path adjusted relative to its containing file and the repository-root path as a fallback. Visual Studio Copilot must have custom instructions enabled to use that pointer.

Claude Code reads CLAUDE.md and uses AGENTS.md only for a directory that has no CLAUDE.md, so a repository that has one would never show Claude Code the index. Wherever a pointer goes into an AGENTS.md, an existing CLAUDE.md in the same directory gets the same managed block. The tool never creates a CLAUDE.md, and it leaves one alone that already imports its sibling AGENTS.md on a line of its own (@AGENTS.md), because that import already delivers the pointer. sync picks up a CLAUDE.md created later and releases one that starts importing AGENTS.md.

Agent skills

Every installed guide that is not supporting also becomes an Agent Skill, so agents that load skills can pick a guide by its description without first reading the index. The default location is .agents\skills\<name>\SKILL.md, the cross-client folder that GitHub Copilot and other agents scan. Claude Code does not read it; see below. A skill is a small stub: front matter (name, description, and metadata recording the package, version, document and the document's SHA-256) and a link to the installed guide, which stays the one verified copy. Skills therefore follow the same approval, hash verification, check and remove rules as guides, and the link rewriting for cross-package references is not duplicated.

  • The skill name is <package>-<document> in lowercase letters, digits and single hyphens, such as trellis-core-trellis-api-core. Two documents of one package with the same file name use their full path; a name that is still ambiguous or longer than 64 characters is shortened and ends in a hash of the document identity.
  • The description is the publisher's description followed by the package and version. It is publisher text that an agent reads as the skill's catalog entry, so approve only packages you trust, as for any guide.
  • Skills are written without a byte order mark, as LF-only text.
  • A skill body is not inert: Claude Code runs a !command`` it finds there when the skill loads. The manifest contract allows spaces, backticks and ! in a document path, so a guide whose package ID, version or path uses anything outside letters, digits and . _ + / - still installs and appears in the index but gets no skill, and init and sync print a warning. The description and metadata are quoted front matter and are not run.
  • A destination that already exists and is not owned by the tool, such as a skill you wrote yourself with the same name, stops init and sync until you review it. --force adopts it.
  • Skills are repository-wide. The index scopes a guide to the projects that restore its package; a skill cannot, so the guide's own text and description do that work.

To write elsewhere or turn skills off, add skillDirectories to .agentdocs\policy.json. Allowed values are ".agents/skills" (the default when the setting is absent) and ".claude/skills", which Claude Code and Copilot both read. "skillDirectories": [] turns skills off; the next sync removes the ones the tool wrote. The empty skills directory stays, because it may be yours.

Claude Code needs .claude/skills. There are two ways to give it the same skills:

  • List both directories. The tool writes every skill twice and keeps both copies hashed, owned and cleaned up. It behaves the same on every operating system, and Copilot CLI 1.0.107 lists each skill once. The Agent Skills specification asks clients to warn about a name collision, so another client may mention the duplicate.

    {
      "schemaVersion": 1,
      "approvedPackages": ["Trellis.Core"],
      "skillDirectories": [".agents/skills", ".claude/skills"]
    }
    
  • Link .claude/skills to .agents/skills. Keep the default and create the link yourself, before or after init: New-Item -ItemType SymbolicLink -Path .claude\skills -Target ..\.agents\skills (or ln -s ../.agents/skills .claude/skills). Claude Code follows the link, and the tool never touches .claude/skills, so sync, check and remove leave it alone. The tool does not create the link and does not notice if it is missing. A link needs Developer Mode or administrator rights on Windows, and a checkout without symbolic link support turns it into a small text file, after which Claude Code sees no skills. Never point skillDirectories at the link itself: the tool refuses to write through a link.

The setting is optional, but an older tool rejects a policy that contains it.

Commit the tool manifest, pointers, policy.json, agent-context.json, the index, the guides, and the skills. agent-context.json records the selected graph and ownership hashes needed for check and safe cleanup after a fresh clone. Keep the packages you approve reviewed: their documents are instructions for an agent that acts with your privileges.

Newly written agent-context.json files use UTF-8 without a BOM, so standard JSON readers can consume them directly. Generated text uses LF line endings; the utf8-lf-no-bom-v1 ownership hashes ignore BOM and line-ending conversions on checkout. To keep .agentdocs files as LF and avoid Git's LF-to-CRLF warnings, add this rule to your repository-root .gitattributes:

.agentdocs/** text eol=lf
.claude/skills/** text eol=lf
.agents/skills/** text eol=lf

AgentDocs does not modify your .gitattributes or normalize existing customer-authored instruction files.

This release writes context schema 1 and reads only schema 1, and it reads policy schema 1 only. Both versions are independent of the package manifest schema. An incompatible change to either file format will use a new schema version and be called out in the release notes. State written by the 0.1 previews with schema 1 is read as is; run agentdocs sync after upgrading the tool, which rewrites only the recorded tool version when nothing else changed. Contexts from development formats before schema 1 are not migrated: remove the old generated context with its matching tool version (or delete the reviewed .agentdocs generated files) and run init again.

After a package upgrade

Nothing runs automatically. After changing a package reference or version, restore and then sync:

dotnet restore --force
dotnet tool run agentdocs sync

init, sync, and check fail without writing when a selected project's restore output is older than its project file or repository-local restore inputs, including Directory.Packages.props, Directory.Build.props, Directory.Build.targets, NuGet.Config, and tracked imports. Repository-local inputs from NuGet's evaluated project references, including transitive references and their per-framework imports, are included in both freshness checks and the recorded graph. Build-only references omitted by NuGet are still excluded. This also applies to check --content-only: stale restore output cannot establish that installed guidance is current. The timestamp check is conservative, so merely touching an input can require another restore.

Project references outside the Git root, such as sibling checkouts, remain supported. AgentDocs warns once per external project per command and skips that project and its reference subtree: their freshness is not checked and their inputs are not included in the recorded restore hash. Selected entry points must still be inside the Git root.

MSBuild evaluations are reused by project path and target framework throughout one command, including overlapping solution and project entry points. The cache is created after any requested restores and discarded when the command ends.

NuGet can leave an unchanged project.assets.json untouched. --force refreshes the successful project.nuget.cache checkpoint even when the resolved graph does not change. For several selected entry points, restore each explicitly, or use dotnet tool run agentdocs sync --restore to restore all recorded entry points before syncing. init --restore and sync --restore pass --force to NuGet; check never restores.

In CI, check out the repository first, restore every recorded entry point, then run check. Restoring a solution does not refresh a separately selected project that is missing from that solution; sync --restore covers both.

The index tells agents to do the same. In CI, dotnet restore --force followed by dotnet tool run agentdocs check --strict --strict-references fails when the installed guidance no longer matches the restored packages or when a hand-written instruction links to a missing file, or when a cross-package reference is unresolved.

The recorded graph tracks every restore input, so even a bump of a package that publishes no guidance changes it and plain check fails until someone runs sync. To fail CI only when the installed guidance, index or pointers would actually change, use dotnet tool run agentdocs check --strict --content-only: a graph that differs only in restore inputs that do not affect what is installed passes, with a note suggesting sync to refresh the record. A modified, missing or outdated installed guide still fails.

If an approved package no longer supplies a guide, or you withdraw its approval, sync removes its previously owned guides and prints a notice. A malformed manifest, bad hash, mixed versions of one approved package, stale selected graph, or modified owned file fails the command without writing; it does not silently install unverified guidance or overwrite your edits. AgentDocs stages the whole desired plan and restores the prior files if a normal I/O or concurrency failure occurs midway through apply. An abrupt process or machine interruption can still leave rollback files; inspect the diff, then re-run with --force or restore the files from Git.

sync, init, and check warn with file and line about missing local Markdown links in AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md, including nested files. They recognize Markdown links and backticked paths, resolve them relative to the instruction file or Git root, and never rewrite hand-authored links. Use --strict to fail before writing if any such link is missing.

Command Purpose
agentdocs init <solution-or-project>... Opt in, create an empty policy if none exists, and install guides for approved packages.
agentdocs sync Update installed guides and the index from the recorded graph and the policy.
agentdocs check Check graph and installed context without writing; useful in CI. --content-only ignores drift that does not change the installed guidance; --strict-references rejects unresolved references and missing headings.
agentdocs remove Remove owned guides, skills, pointers, and context state without touching customer text or the policy.
agentdocs validate <package.nupkg\|directory> For authors: check a package's guidance before publishing. Read-only; needs no repository, restore or policy.

validate is the publisher-side check, so a mistake is caught before a consumer meets it. It reports errors for contract violations (AD001-AD012: manifest shape, unsafe or missing paths, hash mismatches, usage, descriptions, at least one required or on-demand document, duplicate or aliased paths, non-UTF-8 documents, archive entries that would extract onto the same path (same decoded path, case or Unicode alias, or a file that is also a directory), files over the validator's resource limits) and warnings for guidance that is valid but hard to use (AD101-AD109): an oversized required set, links that will not resolve once installed (missing files, headings that do not exist, root-relative paths, and targets that are not installed Markdown such as images or code samples, in Markdown links and in raw HTML href/src), supporting documents that no required or on-demand document reaches, a front matter block that is not valid YAML, Markdown files beside the guidance that the manifest does not list, total guidance size, the number of index entries, and two on-demand documents with the identical description, and declared cross-package references that no Markdown document uses. AD011 rejects unrewritable cross-package links and AD012 rejects package self-references. For nupkgs and extracted package directories, validate reads the single root nuspec only when references are declared so AD012 can compare against the publishing package ID. Documents are read with a Markdown parser (GitHub heading anchors) and a YAML parser. Apart from that bounded nuspec identity read, only the manifest and the documents it declares are read from a package, each within a size limit. It exits 1 on errors, and on warnings with --strict. Use --max-required-bytes N, --max-total-bytes N and --max-indexed-documents N to change the budgets (defaults 32768, 4 MiB and 100) and --format json for machine-readable output on standard output.

init and sync accept --restore to refresh the selected entry points. init also accepts --source-root DIR for additional source directories. Both accept --dry-run to preview, but not together with --restore. The tool refuses unowned destinations and concurrent edits; --force is available only for a reviewed adoption or repair. The current context selects one graph per Git repository; mixed resolved versions of an approved package that publishes guidance, or of an approved target used by a cross-package reference, are rejected rather than silently choosing one project's version. Unreferenced packages without guidance, and packages that are not approved, may resolve to different versions across those projects. Loaded guidance for the same package ID/version must have equivalent document declarations and exact hashes, reference declarations and publisher metadata across all selected scopes; divergent payloads are rejected before writes. After an update commits, failures to remove rollback files or prune empty package directories emit cleanup warnings without reporting the update as failed. Null reference-dependency entries or paths in the context state are rejected with an error before planning an update or modifying files. For freshness checks, NuGet's evaluated per-target restore references are compared against the restored project-reference graph. Build-only references that NuGet omits, such as a SQL project supplying a dacpac, do not cause false stale-assets errors.

Contexts created by earlier previews installed restore hooks. Run agentdocs remove with the version that created them, or delete .agentdocs and the restore imports it added to Directory.Build.targets and Directory.Solution.targets, and then run init again.

Known limits

  • A frontend directory inside a project's own directory (for example a SPA under an ASP.NET project) belongs to that project by the index's rules and inherits its required reading. Separately rooted projects do not.
  • Files compiled into a project from outside its directory are not matched to it.
  • A project outside the selected graph is "not analysed": the index requires nothing for it. Select it in init to cover it.

The manifest format is a convention, not a NuGet standard. An agent needs the repository pointers (or explicit direction from its user) to find the installed index; installing a guide cannot make every agent discover it automatically.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
1.0.3 175 11/8/2026
1.0.2 512 10/19/2026
0.1.0-preview.22 98 10/16/2026
0.1.0-preview.20 373 10/4/2026
0.1.0-preview.19 289 10/1/2026
0.1.0-preview.17 100 10/1/2026
0.1.0-preview.15 69 9/30/2026
0.1.0-preview.14 70 9/30/2026
0.1.0-preview.12 68 9/29/2026
0.1.0-preview.11 70 9/28/2026
0.1.0-preview.10 70 9/28/2026
0.1.0-preview.9 72 9/28/2026