Configuring Presswork

Create a schema-backed presswork.json, select a complete Profile, add repository policy, and validate the result.

Use presswork.json when the Basic Profile alone does not describe the repository or when you want to select it explicitly. Presswork reads this file only at the Repository Root and never merges nested configuration.

1. Choose a Profile

Review the Profile replacement model and Built-in Profile comparison. Select one complete Profile identity. Do not copy settings from the Basic Profile into another Profile in an attempt to inherit it.

2. Create presswork.json

Create this minimal configuration at the Repository Root to select basic@1 explicitly:

{
  "$schema": "https://presswork.sh/schema/config.json",
  "version": 1,
  "profile": {
    "name": "basic",
    "version": 1
  }
}

The top-level version is the Configuration Version. $schema lets compatible editors validate the file against the published schema and offer field documentation and completion. Presswork does not fetch the schema at runtime.

Every Configuration object is strict. Undeclared fields are invalid. An unreadable or invalid presswork.json fails the operation instead of falling back to a Profile.

3. Add repository policy

Add only declarations the repository needs. This schema-conforming example adds a Documentation Directory, a Root Document, and an Index Policy while retaining the complete Basic Profile:

{
  "$schema": "https://presswork.sh/schema/config.json",
  "version": 1,
  "profile": {
    "name": "basic",
    "version": 1
  },
  "markdownDialect": "github",
  "documentationDirectories": ["packages/api/docs"],
  "rootDocuments": ["API-AGENTS.md"],
  "indexes": {
    "packages/api/docs": {
      "document": "packages/api/docs/README.md",
      "heading": "Documentation"
    }
  }
}

Configuration Version 1 supports the github Markdown Dialect. Documentation Directories and Root Documents are additions to the selected Profile. An Index Policy replaces the selected Profile policy only when both use the same Documentation Directory; a policy for another directory is added.

Use the Presswork Configuration reference for exact fields, paths, Document Types, Creation Policies, Templates, required fields, index behavior, and Agent Skill guidance.

4. Validate the configuration

Run a Check from the configured Repository Root:

presswork check

A produced Check Report confirms that Presswork loaded the configuration and identifies the selected Profile and Markdown Dialect. If configuration is invalid or unavailable, fix the named presswork.json using the diagnostic recovery guidance, then run the Check again. The CLI reference owns options, output streams, and exit status. The Check Report reference owns complete and incomplete outcomes and report fields.

Continue with Create a Document Draft after defining a Document Type with a presswork Creation Policy.