---
title: Configuring Presswork
description: 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](/profiles/) and [Built-in Profile comparison](/built-in-profiles/). 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:

```json title="presswork.json"
{
  "$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:

```json title="presswork.json"
{
  "$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](/configuration/) 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:

```sh
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](/cli/#presswork-check) owns options, output streams, and exit status. The [Check Report reference](/check-report/) owns complete and incomplete outcomes and report fields.

Continue with [Create a Document Draft](/create-a-document/) after defining a Document Type with a `presswork` Creation Policy.