kriskrug-wp

内容来源:README.md(说明文档) · 原始地址 · 查看安装指南

原始内容

kriskrug-wp — Operations Hub for kriskrug.co

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

Live site: kriskrug.co (Pagely-hosted WordPress, Aurora kk-aurora theme) Repo: WalksWithASwagger/kriskrug-wp Operating model: Two tracks — see docs/current-state/TWO-TRACK-MODEL.md

This repository is the operations + content hub for 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.

About Kris Krug

Kris Krug is a person, not an organization: a Vancouver-based photographer, AI community builder, and keynote speaker. 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 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/)
  2. Content pipeline — Notion → kriskrug.co publisher with safety guards (see scripts/notion-to-wp/)
  3. Custom WordPress code — schema markup, theme tweaks, helper plugins (see fixes/, inc/, and 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 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

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.

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

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/

The full Python gate needs the packages in requirements-test.txt at the repo root:

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, then read docs/current-state/README.md.

For human contributors

  1. Browse open issues
  2. Read 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 and 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); the Aurora theme itself declares a minimum of PHP 8.0 in 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

Contact

For questions about this repository or Kris Krug:

  • Create an issue in this repository
  • Visit 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. This is Kris's personal operations tooling, not a redistributable package.
  • The Aurora theme (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.