Concepts
Understand Repository Roots, Recognized Documents, Profiles, Rules, and Check outcomes.
The repository’s CONTEXT.md is the canonical authority for Presswork’s domain terms. This page explains how those terms work together.
Repository Root and policy
Presswork evaluates one Repository Root at a time. It discovers the nearest ancestor of the current directory containing a .git file or directory. Files outside that boundary cannot become Recognized Documents or valid local link targets. An explicit --root selects only the supplied boundary and never falls back to ancestor discovery.
The optional presswork.json at the Repository Root selects one complete versioned Profile and may add repository-specific Documentation Directories, Root Documents, Document Types, index policies, and Markdown semantics. Presswork does not search nested directories for more configuration.
A Profile is the repository-wide policy: rules, defaults, Templates, Documentation Directories, and Root Documents. Profile Versions keep that policy explicit so upgrading Presswork does not silently adopt a different documentation contract.
Recognized Documents
Recognized Documents are configured or Profile-provided Root Documents and non-ignored documents discovered recursively in Documentation Directories. Discovery recognizes lowercase .md and .markdown files. Git supplies candidates, so ignored files and directories reached through symbolic links are excluded.
A directly encountered symbolic link can be a Recognized Document only when it resolves to a regular file inside the real Repository Root. Presswork does not traverse a directory through a symbolic link.
With no Presswork Configuration, basic@1 recognizes the docs Documentation Directory and the Root Documents AGENTS.md, CONTEXT.md, ARCHITECTURE.md, and DESIGN.md. Missing locations contribute no Recognized Documents.
Rules
A Rule evaluates documentation against one Profile requirement without changing it. The selected Profile determines which Rules and declarative requirements apply. Rule Scope may cover every Recognized Document or only documents at matching locations.
The current generic Rules validate Markdown destinations, repository-defined and Built-in Document Types and Templates, and authored documentation indexes. Profile-specific requirements can add structure, naming, status, or sequence checks. For example, mattpocock@1 adds requirements for its Architecture Decision Records and optional context documents. The Configuration reference shows how to select a Profile; configuration cannot add executable Rules.
Reports and recovery
A Violation means Presswork completed the relevant evaluation and found documentation that does not satisfy a Rule. Each Violation identifies the source, stable Rule identifier, explanation, and recovery guidance.
An Operational Diagnostic instead means Presswork could not complete part of the Check, such as reading configuration or a required document. Incomplete Checks keep any Violations already found and exit 2. See Check Report for report fields, streams, and exit status.
Document Types and creation
A Document Type defines a repository-specific location, filename, Template, required creation fields, index membership, and preferred Creation Policy. presswork create can initialize a Document Draft for a presswork Creation Policy. The draft still contains explicit Template instructions that must be resolved before validation can pass.
Use the CLI reference for exact commands, the Reference for configuration, and the Glossary for canonical terms.