---
slug: "kriskrug-wp"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/WalksWithASwagger/kriskrug-wp@main/README.md"
repo: "https://github.com/WalksWithASwagger/kriskrug-wp"
source_file: "README.md"
branch: "main"
---
# kriskrug-wp — Operations Hub for kriskrug.co

> The personal site of Kris Krug: photographer, AI community builder, keynote speaker.

**Live site:** [kriskrug.co](https://kriskrug.co/) (Pagely-hosted WordPress, Aurora `kk-aurora` theme)
**Repo:** [WalksWithASwagger/kriskrug-wp](https://github.com/WalksWithASwagger/kriskrug-wp)
**Operating model:** Two tracks — see [`docs/current-state/TWO-TRACK-MODEL.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/docs/current-state/TWO-TRACK-MODEL.md)

This repository is the **operations + content hub** for [kriskrug.co](https://kriskrug.co/). The live WordPress install is not file-synced here (it runs on Pagely). This repo holds everything *adjacent* to the site: audit snapshots, draft content before publication, deployment-ready code snippets, packaged helper plugins, and the Notion → WordPress publisher.

**If you're an AI agent landing in this repo cold, start at [`AGENTS.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/AGENTS.md).**

## About Kris Krug

Kris Krug is a person, not an organization: a Vancouver-based photographer, AI community builder, and keynote speaker. [kriskrug.co](https://kriskrug.co/) is his personal site, covering his photography, writing, speaking, and community work.

Kris also convenes the BC + AI ecosystem community, but that project lives at [bc-ai.ca](https://bc-ai.ca/) and in its own repos. This repo is only about keeping his personal site healthy: publishing posts, maintaining the Aurora theme, and keeping SEO and schema in shape.

## Repository Purpose

This repository is used for:

1. **Site audits + state snapshots** of the live kriskrug.co WordPress install (see [`docs/current-state/`](https://github.com/WalksWithASwagger/kriskrug-wp/tree/HEAD/docs/current-state/))
2. **Content pipeline** — Notion → kriskrug.co publisher with safety guards (see [`scripts/notion-to-wp/`](https://github.com/WalksWithASwagger/kriskrug-wp/tree/HEAD/scripts/notion-to-wp/))
3. **Custom WordPress code** — schema markup, theme tweaks, helper plugins (see [`fixes/`](https://github.com/WalksWithASwagger/kriskrug-wp/tree/HEAD/fixes/), [`inc/`](https://github.com/WalksWithASwagger/kriskrug-wp/tree/HEAD/inc/), and [`plugins/`](https://github.com/WalksWithASwagger/kriskrug-wp/tree/HEAD/plugins/))
4. **Aurora theme work** — canonical theme source now tracked on `main` (merged via PR #129), with lane-scoped feature branches for larger slices; `aurora/v2` and `aurora/v3-reconcile` are preserved evidence/reconcile branches, not wholesale merge targets
5. **Issue tracking + project management** for fixes, content, and theme work

### Why a Separate Repo?

The live WordPress site is not file-synced with this repo (it runs on Pagely). This repo holds everything *adjacent* to the site: audit data, draft content before publication, deployment-ready code snippets, and runbooks. See [Project Structure](#project-structure) for the layout.

## Project Structure

```
content/drafts/                  # Notion-derived post drafts before publication
  └── YYYY-MM-DD-<slug>/         # post.md, post.html, images/, seo-meta.md, etc.

content/source-packs/            # Curated source packs for page/content overhauls
  └── keynotes-2026/             # Speaking/Work/About payloads and source notes for issue #76

backup/                          # Manifests and page-level rollback snapshots; archives are ignored
  └── YYYYMMDD-HHMMSS/           # Small REST/HTML snapshots used for targeted rollback

scripts/notion-to-wp/            # Notion → kriskrug.co publisher
  ├── kk_notion_to_wp.py         # Single-file CLI: fetch, convert, upload, publish
  ├── block_rules.py             # Notion block → Gutenberg block mapping
  └── README.md                  # Setup + safety notes

fixes/                           # Production-ready code snippets / migrations
  ├── schema-snippets.php        # JSON-LD (Person + WebSite + Article + Breadcrumb + Service)
  ├── schema-snippets-deployed.php  # The version actually running on prod
  ├── llms.txt                   # Deployment-ready curated llms.txt for AI search
  ├── llms-txt-template.md       # Deployment and rollback guide for llms.txt
  ├── robots-txt-update.txt      # Two AI-crawler stance options
  └── issue-*.{css,php,md}       # Older queued fixes from earlier batches

plugins/
  └── kk-sidebar-promos/         # Packaged helper plugin for auto-expiring sidebar promos

docs/current-state/              # Frozen baseline snapshot plus dated recovery/redesign handoffs
  ├── README.md                  # Index of the snapshot
  ├── SITE_INVENTORY.md          # Live-site fingerprint: host, theme, plugins, content shape
  ├── REPO_STATE.md              # What's actually built vs. just documented
  ├── ACCESS_CHANNELS.md         # MCP / REST / Chrome / SSH — what works today
  ├── BACKUP_PLAN.md             # The four pieces of a real WP backup + paths to get them
  ├── ROLLBACK_PLAYBOOK.md       # If a change breaks prod, here's the order of operations
  ├── SEO_AUDIT.md               # Technical SEO + on-page + AI/generative-search readiness
  ├── CONTENT_AUDIT.md           # Per-page review of all 34 pages + recent post inventory
  ├── FIX_QUEUE.md               # P0 → P3 backlog
  ├── ROADMAP.md                 # Where this is heading next
  ├── FULL-AUDIT-ROADMAP-2026-05-18.md # Current queue audit + next roadmap
  ├── INCIDENT-2026-05-15-overwritten-post.md   # Postmortem for the connector overwrite
  └── raw/                       # Underlying API/HTML evidence behind the audit

issues-to-create/                # Markdown drafts of GitHub issues waiting to be filed

inc/                             # Custom WordPress modules (e.g., digital-composting CPT)

skills/                          # Claude Code skills used in this repo
.github/                         # PR validation plus parked historical agent-swarm definitions
```

### Where to start

- **Reading the site state:** `docs/current-state/README.md`
- **Planning next work:** the newest dated `docs/current-state/CURRENT-STATE-*.md` and `docs/current-state/WORK-PLAN-*.md` (the index in `docs/current-state/README.md` names the current ones)
- **Latest startup truth:** the newest `docs/current-state/reports/morning-truth-*.md` (run `make morning-truth` for a fresh one; dated links go stale fast, so always take the newest)
- **Latest diagnostic truth:** `docs/current-state/DIAGNOSTIC-POLISH-2026-05-20.md`
- **Longer roadmap references:** `docs/current-state/ROADMAP.md` and `docs/current-state/FIX_QUEUE.md`
- **Publishing a Notion post:** `scripts/notion-to-wp/README.md`
- **Reviewing staged drafts:** `content/drafts/README.md`
- **Read-only startup status:** `make status-readonly` prints current repo/site signals without writing a report
- **Filing an issue:** `issues-to-create/` for drafts; existing ones at [WalksWithASwagger/kriskrug-wp/issues](https://github.com/WalksWithASwagger/kriskrug-wp/issues)

## How work happens here

Two parallel lanes. Keep one lane per commit — don't mix unrelated theme/content changes in the same commit.

### Track A — Content + SEO (on `main`, weekly cadence)

Notion → kriskrug.co publishing, post-publish enrichment, schema maintenance, alt-text batches, category sweeps, GSC + sitemap health.

- Publish a post: [`scripts/notion-to-wp/README.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/scripts/notion-to-wp/README.md)
- Enrichment + link-graph helper: [`scripts/notion-to-wp/text_polish.py`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/scripts/notion-to-wp/text_polish.py)
- Active backlog: [`docs/current-state/FIX_QUEUE.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/docs/current-state/FIX_QUEUE.md), [`docs/current-state/SITE-AUDIT-2026-05-16.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/docs/current-state/SITE-AUDIT-2026-05-16.md)
- Deployed schema: [`fixes/schema-snippets-deployed.php`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/fixes/schema-snippets-deployed.php)

### Track B — Aurora theme (on `main` via lane-scoped branches)

FSE theme rebuild and polish. Touches `theme/kk-aurora/`, FSE templates, theme.json. Avoid bundling theme edits with content publishing changes in the same commit.

- Current branch model (2026-05-29): start Track B work from `main` on a
  lane-scoped `codex/...` branch. Use `aurora/v3-reconcile` only as deferred
  evidence for specific theme-polish files, and keep `aurora/v2` references as
  historical context unless a dated handoff says otherwise.
- Side-worktree safety refresh (2026-06-02): do not edit
  `/Users/kk/Code/kriskrug-wp-aurora-keynote`
  (`codex/aurora-keynote-redesign`), `/Users/kk/Code/kriskrug-wp-aurora-reconcile`
  (`aurora/v3-reconcile`), or the locked
  `/Users/kk/Code/kriskrug-wp/.claude/worktrees/agent-aec50fddbd7207f80`
  (`aurora/v2`) directly. Treat them as evidence or historical side branches
  unless a maintainer explicitly resumes one.
- Migration plan: [`docs/current-state/AURORA-MIGRATION-PLAN.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/docs/current-state/AURORA-MIGRATION-PLAN.md)

### Which track am I in?

If you're editing a post, page, schema, redirect, or category → Track A. If you're editing theme files or FSE templates → Track B. Use the two-track model doc for historical context, but prefer the 2026-05-24 handoff docs for current branch/layout truth.

## Getting Started

### What runs here

There is no local app server. The live WordPress site runs on Pagely and is not file-synced with this repo. "Running" this repo means the CLI and validation surfaces:

- `make status-readonly` or `make morning-truth` for startup truth
- `make test` for the local test suite (Python, JavaScript syntax, plugin and theme smoke)
- `make validate` for the WordPress PHP security ruleset (run `composer install` first)
- `make verify` for the standard local gate (test + docs-truth-check + validate)
- The Notion publisher CLI in [`scripts/notion-to-wp/`](https://github.com/WalksWithASwagger/kriskrug-wp/tree/HEAD/scripts/notion-to-wp/)

The full Python gate needs the packages in [`requirements-test.txt`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/requirements-test.txt) at the repo root:

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-test.txt
make python-test PYTHON=python
```

### For agents
Start at [`AGENTS.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/AGENTS.md), then read [`docs/current-state/README.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/docs/current-state/README.md).

### For human contributors
1. Browse [open issues](https://github.com/WalksWithASwagger/kriskrug-wp/issues)
2. Read [`CONTRIBUTING.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/CONTRIBUTING.md)
3. Use issue templates when filing new issues
4. Run `composer install` once, then `make verify` before submitting code changes

### Historical / parked: GitHub Actions agent swarm
`.github/agents/` defines an older issue-to-PR pipeline (orchestrator → analyzer → test-writer → implementer → QA → reviewer → PR creator). It produced PRs #71 and #72 in May 2026 and is not used by current sessions. `agent-pr-generator.yml` is now a manual, read-only diagnostic stub and no longer runs from the `auto-implement` label. `test-pr.yml` remains active PR validation. See [`docs/architecture.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/docs/architecture.md) and [`docs/automation-guide.md`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/docs/automation-guide.md) for reference if/when the swarm is rebuilt intentionally.

## Technology Stack

- **Platform:** WordPress **7.0.1** on Pagely (production), Aurora `kk-aurora` theme (live may lag repo — check CURRENT-STATE)
- **Content pipeline:** Python (Notion API → WordPress REST API)
- **Custom code:** PHP snippets (Code Snippets plugin on prod), `inc/digital-composting.php`, and packaged helper plugins such as `plugins/kk-sidebar-promos/`
- **CLI Tools:** GitHub CLI (`gh`), Claude Code / Cursor agents
- **Languages:** PHP, JavaScript, Python, Bash
- **CI runtimes:** PHP 8.2, Python 3.12, Node 20 (pinned in [`.github/workflows/test-pr.yml`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/.github/workflows/test-pr.yml)); the Aurora theme itself declares a minimum of PHP 8.0 in [`theme/kk-aurora/style.css`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/theme/kk-aurora/style.css)

## Issue Labels

- `bug` - Something isn't working
- `enhancement` - New feature or improvement
- `accessibility` - WCAG compliance and a11y improvements
- `performance` - Speed and optimization
- `seo` - Search engine optimization
- `content` - Content updates and UX
- `documentation` - Documentation improvements
- `auto-implement` - Historical automation-intent label; does not currently start the parked Agent PR Generator
- `needs-human-review` - Requires manual review

## Project Links

- **Live Site:** [kriskrug.co](https://kriskrug.co/)
- **Events:** [Luma Calendar](https://lu.ma/kk)
- **GitHub:** [WalksWithASwagger/kriskrug-wp](https://github.com/WalksWithASwagger/kriskrug-wp)
- **Issues:** [github.com/WalksWithASwagger/kriskrug-wp/issues](https://github.com/WalksWithASwagger/kriskrug-wp/issues)

## Contact

For questions about this repository or Kris Krug:

- Create an issue in this repository
- Visit [kriskrug.co](https://kriskrug.co/) for general inquiries

## License

Licensing is mixed on purpose:

- The repo's own tooling, scripts, and docs are declared `proprietary` in [`composer.json`](https://github.com/WalksWithASwagger/kriskrug-wp/blob/HEAD/composer.json). This is Kris's personal operations tooling, not a redistributable package.
- The Aurora theme ([`theme/kk-aurora/`](https://github.com/WalksWithASwagger/kriskrug-wp/tree/HEAD/theme/kk-aurora/)) is GPL-2.0-or-later, as declared in its `style.css`. WordPress themes are GPL derivatives, so the theme carries the GPL even though the surrounding repo does not.
- WordPress core and third-party plugins/themes keep their own licenses.