Imported from avolent/cortex (AGENTS.md). Install upstream with npx skills add avolent/cortex. Copyright stays with the author.

AGENTS.md — cortex

This file gives AI agents the context and rules they need to work in this project. It follows the AGENTS.md open standard with project conventions on top (cura-managed sections + Common/Project Practices registries — see Practice types below).

The base section below is managed by cura. Run cura sync to pull upstream changes. Everything outside the markers is yours to edit freely.

How tools see this file in your project:

Bootstrap — delete after filling in

Inspect the project (README, go.mod/package.json/etc., .github/workflows/) to fill in any {placeholders} or YYYY-MM-DD values in this file — frontmatter included. Run cura lint to verify, then delete this section.

Project overview

cortex is a tiny zero-config Go binary that turns any folder of markdown into a navigable wiki: point it at a repo and it serves a sidebar of every .md file plus rendered HTML at http://localhost:8090 (loopback by default; -addr :8090 exposes it on the LAN). It also renders the whole tree to static HTML for hosting (-export), and live-reloads the browser on file changes via SSE. Distributed via go install; its own docs site is published to cortex.wiki through GitHub Pages.

Tech stack

• Language / runtime: Go 1.26.2 (go.mod)
• Build tool: go build (Go toolchain; no Makefile)
• Test framework: Go standard testing (main_test.go)
• CI/CD: GitHub Actions (.github/workflows/pages.yml)
• Hosting: GitHub Pages for the docs site (cortex.wiki); the binary itself is distributed via go install
• Key external services: none — runtime deps are github.com/gomarkdown/markdown (rendering) and github.com/fsnotify/fsnotify (live reload)

Build, test, and dev commands

go install github.com/avolent/cortex@latest  # install the released binary
go build -o cortex .                          # build from source
go test ./...                                 # run tests
gofmt -w .                                    # format
cortex -dir <path> -export ./out              # render the wiki to static HTML

Practice types

Both the Common Practices and Project Practices tables below use the same row Types:

• Rule — agent MUST enforce on every relevant action.
• Convention — preferred pattern; agent SHOULD follow.
• Workflow — there's a script or make target for this; follow Detail.
• Validator — automated check; agent shouldn't duplicate manually.
• Reference — informational; agent loads from Detail on demand.

Detail column points to authoritative source (file, anchor, script, or URL). Use — if Summary fully captures the row.

Both tables have a Category column — a short lowercase label grouping rows by the area of work they govern (e.g. security, git, workflow). Use it to pull all relevant practices before acting in a given context without having to read the whole table.

How to use these tables:

• Before acting (committing, pushing, modifying code, etc.), check both tables for relevant Rules and Conventions. Names are kebab-case and intent-revealing.
• Look up a specific Practice by name: grep "<name>" AGENTS.md (e.g. grep "no-secrets" AGENTS.md).
• Filter by Type: grep "^| Rule" AGENTS.md returns all Rules; same pattern for Convention / Workflow / Validator / Reference.
• Filter by Category: grep "| security |" AGENTS.md returns all security practices across both tables; same pattern for any category label.
• Common Practices apply to any project; Project Practices apply only here. Both are equally binding for work IN this project.

Common Practices

This section is managed by cura. Run cura sync to update from upstream. Don't edit manually — changes will be overwritten on next sync.

Project Practices

Local additions specific to this project. Append rows freely. This section is never touched by cura.

Category is a short lowercase label for the area of work the row governs. Suggested values: git, testing, e2e, handler, security, domain, docs, reference — or any label that fits your project.