initial commit: codex draft

configurations.md

@@ -0,0 +1,99 @@
+# Configuration Reference
+
+This document defines every JSON field for both the global config and per-directory manifests.
+
+## Global Config (`~/.config/wp-materialize/config.json`)
+
+Top-level fields:
+
+1. `wordpress_root` (string, required)
+   Path to the WordPress root directory where the `wp` CLI is executed.
+2. `repo_storage_dir` (string, required)
+   Directory where git repositories are cloned or updated.
+3. `git_repositories` (array, optional)
+   List of git repositories to manage. Default is an empty list.
+4. `directories` (array, optional)
+   List of non-git directories to manage. Default is an empty list.
+
+`git_repositories` entries:
+
+1. `name` (string, required)
+   Stable identifier for the repository. Used to build post identity.
+2. `url` (string, required)
+   Git clone URL.
+3. `branch` (string, optional, default `main`)
+   Branch to checkout and pull.
+4. `root_subdir` (string, optional)
+   Subdirectory within the repo that contains `.wp-materialize.json` and content.
+   If omitted or `null`, the repo root is used.
+
+`directories` entries:
+
+1. `name` (string, required)
+   Stable identifier for the directory. Used to build post identity.
+2. `path` (string, required)
+   Filesystem path to the directory.
+3. `root_subdir` (string, optional)
+   Subdirectory within the directory that contains `.wp-materialize.json` and content.
+   If omitted or `null`, the directory root is used.
+
+## Per-Directory Manifest (`.wp-materialize.json`)
+
+Each managed directory must contain a manifest. Manifests define a scope boundary.
+No implicit traversal is allowed; subdirectories must be listed explicitly.
+
+Top-level fields:
+
+1. `categories` (object, optional)
+   Inherited category paths for this directory and its children.
+2. `tags` (object, optional)
+   Inherited tags for this directory and its children.
+3. `subdirectories` (object, optional)
+   Explicit list of subdirectories to traverse.
+4. `files` (object, optional)
+   Mapping of Markdown file names to file-level configuration.
+
+`categories`, `tags`, and `subdirectories` objects:
+
+1. `content` (array of strings, optional)
+   List of values for the given field.
+   For `categories`, each string is a hierarchical path such as `Systems/Infrastructure`.
+   For `subdirectories`, each string is a directory name under the current directory.
+2. `inherit` (boolean, optional, default `true`)
+   If `true`, append to the parent effective list.
+   If `false`, replace the parent list entirely.
+
+`files` entries:
+
+Each key is a Markdown file name (relative to the manifest directory).
+Each value is an object with the following fields:
+
+1. `title` (string, required if `use_heading_as_title` is not set)
+   Explicit WordPress post title.
+2. `use_heading_as_title` (object, optional)
+   Extracts a heading from the Markdown as the title and removes that heading
+   from the body while promoting remaining headings by one level.
+3. `categories` (object, optional)
+   Overrides categories for this file. Uses the same `content` and `inherit` fields
+   as the top-level `categories` object.
+4. `tags` (object, optional)
+   Overrides tags for this file. Uses the same `content` and `inherit` fields
+   as the top-level `tags` object.
+
+`use_heading_as_title` object:
+
+1. `level` (integer, required)
+   Heading level to extract, from `1` to `6`.
+2. `strict` (boolean, optional, default `true`)
+   If `true`, exactly one matching heading must exist.
+
+## Post Identity
+
+Each post is identified with:
+
+```
+_wp_materialize_source = <source_name>:<relative_path>
+```
+
+`source_name` is the `name` from the global config entry, and `relative_path` is
+relative to the repo or directory root used for identity resolution.