nasc-cli

nasc CLI

nasc, ainmfhocal firinscneach (masculine noun): genitive singular naisc, plural naisc

1. link, tie, bond
2. clasp
3. collar (for tethering an animal)

nasc, briathar (verb): to bind, to tie, to link, to connect. Verbal noun: nascadh.

From Irish (Gaeilge).

nasc is a single static binary that onboards a repository's existing markdown docs for AI-agent consumption and enforces a simple YAML front matter in CI. It marks docs with agent-navigation YAML metadata, generates a docs index for agents, and validates the whole docs corpus against a declared schema.

AI coding agents are expensive at navigating documentation. When docs carry no metadata, an agent falls back on ls, grep, and cat, reading whole files just to find out whether they matter. With nasc, agents can decide what to open in repository, without reading everything first.

Install

Requires Go 1.25 or newer.

go install github.com/aireilly/nasc-cli/cmd/nasc@latest

Or build from a clone:

git clone https://github.com/aireilly/nasc-cli
cd nasc-cli
go build -o nasc ./cmd/nasc

Quick start

# Describe what frontmatter your corpus should carry.
nasc schema init --preset agent-context

# Look at what you already have, and let nasc propose a schema.
nasc schema infer --write

# Backfill metadata from file facts and git history. Review the patch before writing.
nasc mark --tier file,git --patch
nasc mark --tier file,git --write

# Generate the index agents read first.
nasc index --output AGENTS.md

# Gate it in CI. Exit code 3 fails the job.
nasc validate

Add an optional LLM tier when you want a derived one-line description or tags. nasc never vendors an SDK or holds an API key. It shells out to an agent CLI you already run:

nasc mark --tier file,git,llm --llm-cmd "claude -p" --patch

Commands

nasc schema init [--preset agent-context|minimal]
nasc schema infer [--write]
nasc mark [--tier file,git,llm] [--dry-run|--write|--patch] [--llm-cmd <cmd>] [--force]
nasc index [--output <file>] [--template <file>] [--strict]
nasc validate [--severity error|warn] [--json]
nasc get <path> [key]
nasc doctor

How it works

A three-stage in-memory pipeline runs on every invocation:

walk repo → parse each doc (frontmatter + body) → one of { mark | index | validate }

The walker streams markdown paths, honouring .gitignore and .nascignore and always skipping .git/, .nasc/, node_modules/, and vendor/. Parsers produce a Doc per file. The chosen verb consumes the slice. Nothing persists between runs, so each invocation is a clean read of the working tree, which is what a CI job wants.

Write-back edits frontmatter through a yaml.Node round-trip and an atomic file replace, so your key order, comments, and body survive untouched. If a file changes underneath a mark --write, the run stops with exit code 5 rather than clobber it.

Exit codes

Configuration

.nasc/config.yaml, every key optional:

root: .
include: ["**/*.md", "**/*.mdx"]
exclude: ["CHANGELOG.md", "node_modules/**"]

mark:
  llm_cmd: ""
  llm_excerpt_bytes: 2000

index:
  template: templates/agents-index.tmpl
  output: AGENTS.md

output:
  default_format: auto   # auto | table | jsonl

License and attribution

Apache-2.0. See LICENSE for the full text.

The convention of writing a doc's description as a load-or-skip trigger, rather than a topic summary, was informed by the code-docs project by Laura Armstrong. No code, configuration, prompt text, or documentation from that project is included in or derived from nasc.

Contributions use a DCO. Sign your commits with git commit -s.