initial commit: codex draft

README.md

@@ -0,0 +1,113 @@
+# wp-materialize
+
+`wp-materialize` is an automation compiler that materializes specified Markdown files into WordPress posts.
+Git/filesystem state is the single source of truth; WordPress is a derived view.
+
+## Install
+
+```bash
+python -m pip install -e .
+```
+
+## Source Layout
+
+The `wp_materialize` package lives directly under `src/` (single-package mapping).
+
+## Documentation
+
+- [configurations.md](configurations.md)
+- [examples.md](examples.md)
+
+## Configuration
+
+Global config is required and must be a JSON object with these fields:
+
+1. `wordpress_root` (string, required): Path where `wp` CLI is executed.
+2. `repo_storage_dir` (string, required): Directory where git repos are cloned.
+3. `git_repositories` (array, optional): Git repos to manage.
+4. `directories` (array, optional): Non-git directories to manage.
+
+`git_repositories` entries:
+
+1. `name` (string, required): Stable identifier for the repo.
+2. `url` (string, required): Git clone URL.
+3. `branch` (string, optional, default `main`): Branch to checkout.
+4. `root_subdir` (string, optional): Subdirectory that contains manifests/content.
+
+`directories` entries:
+
+1. `name` (string, required): Stable identifier for the directory.
+2. `path` (string, required): Filesystem path.
+3. `root_subdir` (string, optional): Subdirectory that contains manifests/content.
+
+Global config (required):
+
+```
+~/.config/wp-materialize/config.json
+```
+
+Example:
+
+```json
+{
+  "wordpress_root": "/var/www/wordpress",
+  "repo_storage_dir": "/home/user/wp-materialize-repos",
+  "git_repositories": [
+    {
+      "name": "content-repo",
+      "url": "https://github.com/example/content-repo.git",
+      "branch": "main",
+      "root_subdir": "posts"
+    }
+  ],
+  "directories": [
+    {
+      "name": "local-notes",
+      "path": "/home/user/notes",
+      "root_subdir": "wordpress"
+    }
+  ]
+}
+```
+
+State is stored separately (created on first successful apply):
+
+```
+~/.config/wp-materialize/state.json
+```
+
+## Usage
+
+Dry-run evaluation:
+
+```bash
+wp-materialize evaluate
+```
+
+Apply (evaluate, then materialize):
+
+```bash
+wp-materialize apply
+```
+
+Skip git sync:
+
+```bash
+wp-materialize apply --no-sync
+```
+
+## Manifests
+
+Each managed directory must contain a `.wp-materialize.json` manifest. See `configurations.md` for the manifest guide.
+
+## Python Prerequisites
+
+1. Python 3.10+
+2. Packages:
+   - `Markdown>=3.6`
+
+Install dependencies:
+
+```bash
+python -m pip install -r requirements.txt
+```