agentleFS
seznamseznam/jailoc/docs/AGENTS.md

jailoc

AGENTS.md44 starsChanged 5 days agoMITView on GitHub

Each page belongs to exactly one quadrant. Do not mix purposes within a page.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository5 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No filler sentences ("In this section we will…") — get to the point

    line 70
  2. Distinctive:

    No temporal language — describe behaviour as timeless fact, not as a change from a previous state.

    line 71
  3. Distinctive:

    Do not document what is safe or harmless — only document restrictions, warnings, and breaking changes.

    line 72
  4. Very specific:

    Create the .md file in the correct Diátaxis directory

    line 87
  5. Very specific:

    Add it to nav: in mkdocs.yml under the matching section

    line 88
  6. Very specific:

    Add a link from index.md in the appropriate section

    line 89
  7. Distinctive:

    When a code change affects user-facing behaviour, update all docs that describe it

    line 93
  8. Distinctive:

    If a how-to references a feature that changed, verify the steps still work

    line 95
  9. Very specific:

    When adding, removing, or renaming a doc page, update docs/llms.txt — it lists all pages with descriptions following the llmstxt.org spec

    line 96

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

docs/AGENTS.md

Documentation Stack

  • Framework: Diátaxis — four documentation modes, each with distinct purpose and voice
  • Generator: MkDocs with Material theme (mkdocs.yml)
  • Plugins: macros (template variables like {{ version }})
  • Extensions: admonition, pymdownx.details, pymdownx.superfences (with Mermaid custom fence)
  • Custom CSS: stylesheets/extra.css — hero image, code block, table, and typography overrides
  • Build: zensical + mkdocs-macros-plugin → GitHub Pages on v* tags

Diátaxis Structure

Each page belongs to exactly one quadrant. Do not mix purposes within a page.

DirectoryQuadrantPurposeVoice
tutorials/Learning-orientedWalk the reader through doing something for the first time"Follow along with me…" — second person, step-by-step, no unexplained jumps
how-to/Goal-orientedSolve a specific, already-understood problem"Do X, then Y" — imperative, assumes context, minimal explanation
reference/Information-orientedExact technical descriptions of every field, flag, and behaviourDry, complete, consistent structure — tables, no narrative
explanation/Understanding-orientedExplain why things work the way they doDiscursive prose, assumes the reader wants to understand, not act

Current pages

docs/
  index.md                         Landing page — hero image, why jailoc, link hub
  development.md                   Contributor guide — build, test, CI, conventions
  tutorials/
    getting-started.md             Install + first workspace walkthrough
  how-to/
    installation.md                Install, host requirements, VM runtime
    workspace-configuration.md     Workspace selection, paths, env, mounts, snapshots, ports, protect_git, Docker, resources, reload vs restart
    custom-images.md               URL Dockerfile presets, local Dockerfiles, build context, isolated builds
    network-access.md              allowed_hosts, allowed_networks, filtered DNS, verifying rules
    secrets.md                     from_env / from_file / from_command secrets, rotation with reload
    ssh-git-passthrough.md         SSH and GPG agent forwarding, Git config and known_hosts snapshots
    sessions.md                    Start, attach, continue and list agent sessions; logs
    coding-agents.md               Choose the coding agent (agent, agents.<name>), several agents per project
    tui-plugin.md                  Workspace indicator in the agent UI
    migrate-from-v1.md             Convert a v1 (Docker) config with jailoc migrate
    troubleshooting.md             Logs, common errors, VM state files
  reference/
    cli.md                         All subcommands with flags and examples
    configuration.md               Every config.toml field, types, defaults, validation rules
    image-resolution.md            How the workspace image is chosen, built and exported
    default-image.md               Tools in the embedded base image
    overlay-compatibility.md       Rules for workspace Dockerfile overlays
  explanation/
    overview.md                    Startup sequence, why a VM
    threat-model.md                What jailoc protects against and what it does not
    security-boundaries.md         Trust levels, enforced boundaries, crossing channels, out-of-scope risks
    architecture.md                Builder/workspace VMs, jailoc-guest, shares, persistent home
    network-isolation.md           Userspace network broker, IPv4/IPv6 policy, filtered DNS
    secrets.md                     Secret delivery over SSH, tmpfs storage in the guest
    resource-use.md                Memory reclaim, zram, image cache, disks, broker limits, log rotation
    alternatives.md                Comparison with other sandboxes and VMMs, why libkrun and a userspace broker
  blog/
    agent-config.md                v2.4 read-only agent config snapshots post (outside Diátaxis; temporal language allowed)
    network-rules.md               v2.4 network rules & setups post (outside Diátaxis; temporal language allowed)
    jailoc-2.md                    v2 release post (outside Diátaxis; temporal language allowed)

Writing Conventions

Language and tone

  • English only (project was migrated from Czech)
  • Second person for tutorials and how-to ("you"), third person for reference and explanation
  • Imperative mood for how-to headings ("Configure network access", not "Configuring network access")
  • No filler sentences ("In this section we will…") — get to the point
  • No temporal language — describe behaviour as timeless fact, not as a change from a previous state. Avoid "now", "used to", "no longer", "previously", "newly", "has been added", "was replaced". Write as if the reader has no knowledge of prior versions.
  • Do not document what is safe or harmless — only document restrictions, warnings, and breaking changes. Assume anything not mentioned is acceptable.

Formatting

  • # for page title, ## for main sections, ### for subsections — no deeper than ####
  • Code blocks with language hint: ```bash, ```toml, ```go
  • Tables for structured reference data (config fields, CLI flags, port assignments)
  • Admonitions for warnings and notes: !!! warning, !!! note, !!! danger — not blockquotes
  • Diagrams: hand-written SVG in the section's img/ directory, embedded as ![descriptive alt text](img/<name>.svg) (style and steps in the svg-diagrams skill, .agents/skills/svg-diagrams/)
  • Internal cross-references use relative paths: [text](../how-to/network-access.md)

Template variables

  • {{ version }} expands to $GITHUB_REF_NAME or "latest" — use it in install commands
  • Provided by the macros plugin via extra.version in mkdocs.yml

Adding a new page

  1. Create the .md file in the correct Diátaxis directory
  2. Add it to nav: in mkdocs.yml under the matching section
  3. Add a link from index.md in the appropriate section
  4. Cross-link from related pages where it aids navigation

Updating existing pages

  • When a code change affects user-facing behaviour, update all docs that describe it
  • Reference pages must stay in sync with code — field names, defaults, validation rules
  • If a how-to references a feature that changed, verify the steps still work
  • When adding, removing, or renaming a doc page, update docs/llms.txt — it lists all pages with descriptions following the llmstxt.org spec

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.