coding-os 0.3.2__py3-none-any.whl

templates/vue-nuxt/skills/vue-nuxt/references/anatomy.md

@@ -0,0 +1,60 @@
+<!-- domain:VUENUXT | layer:reference | ssot:true | updated:2026-06-27 -->
+# Vue + Nuxt Anatomy
+
+> P: Canonical file map + entity recipes for the Nuxt 3 (file-routing, composables, Pinia) stack.
+> R: Adding any `.vue`/`.ts` under `src/frontend/`, or routing a frontend task.
+> S: Reading backend / mobile code — wrong stack.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: `src/templates/vue-nuxt/scaffold-boundary.yaml`.
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Page / route | `pages/<path>.vue` | `<path>.vue` | components, composables | File-based route; `useFetch` in setup |
+| Component | `components/<Name>.vue` | `<Name>.vue` | — | Auto-imported, presentational |
+| Composable | `composables/use<Name>.ts` | `use<Name>.ts` | stores | `useX()` state + data access logic |
+| Store | `stores/<name>.ts` | `<name>.ts` | — | Pinia store, one per domain |
+| Server route | `server/api/<name>.ts` | `<name>.ts` | — | Nitro endpoint (server-only) |
+| Test | `<file>.test.ts` | `<file>.test.ts` | source under test | Vitest |
+
+## 3. Entity recipes
+
+### Add a new component
+- **Trigger:** "add a `<Name>` UI block".
+- **Files emitted:** `components/<Name>.vue` (+ test).
+- **Steps:**
+  1. `<script setup>`, props in / emits out; rely on auto-import.
+
+### Add a new route
+- **Trigger:** "add a `/<path>` page".
+- **Files emitted:** `pages/<path>.vue` (+ `composables/use<Name>.ts` if it needs data).
+- **Steps:**
+  1. Fetch with `useFetch`/`useAsyncData` in setup — never a bare `$fetch`.
+  2. Server-only logic and secrets go to `server/api/`.
+
+### Add a new test
+- **Trigger:** any new component / composable.
+- **Files emitted:** `<file>.test.ts` next to source.
+- **Steps:**
+  1. Vitest + `@vue/test-utils`; `vue-tsc` for types.
+
+## 4. Conventions
+
+#### Naming
+- Components: `PascalCase.vue`. Composables: `use<Name>.ts`; stores: `kebab-case.ts`.
+
+#### Test colocation
+- Colocated: `<file>.test.ts` next to source.
+
+#### Dependency rules
+- ✓ page → composable → Pinia store.
+- ✗ no module-level mutable singletons (they leak across SSR requests).
+- ✗ `src/frontend/` never imports from `src/backend/` / `src/mobile/` — share via `src/shared/`.

templates/vue-nuxt/stack.yaml

@@ -0,0 +1,61 @@
+version: 1
+id: vue-nuxt
+language: typescript
+label: "Vue 3 + Nuxt + TypeScript"
+category: frontend
+
+structure:
+  root: src/frontend
+  tree: |
+    src/frontend/
+    ├── nuxt.config.ts
+    ├── app.vue            # root shell only
+    ├── pages/             # file-based routing
+    ├── components/        # auto-imported, PascalCase
+    ├── composables/       # useX() naming, auto-imported
+    └── server/api/        # Nitro server routes
+  notes: "Nuxt 3 conventions; state via Pinia per state-management skill hierarchy"
+primary_skill: vue-nuxt
+skills: [vue-nuxt]
+
+substitutions:
+  DOMAIN_ROUTES: "Frontend→`docs/playbooks/nuxt-app.md`"
+  SKILL_ROUTES: "Frontend→`vue-nuxt`"
+  ENGINEERING_RULE_ROUTING: "Frontend→`docs/engineering/nuxt-rules.md`, a11y→`a11y` skill"
+  TOOL_ROUTING_IMPL: "`lint-frontend`, `test-frontend`, `build-frontend`"
+  VERIFY_FRONTEND_GLOB: "`src/frontend/`"
+  VERIFY_FRONTEND_SUITES: "lint-frontend + test-frontend"
+  VERIFY_FRONTEND: "`cd src/frontend && npm run lint && npm test`"
+  QUICK_ROUTING: |-
+    - Nuxt page / component task → [Nuxt App Playbook](./playbooks/nuxt-app.md)
+    - Composable / state work → [Nuxt App Playbook](./playbooks/nuxt-app.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-NUXT` → `./playbooks/nuxt-app.md`
+    - `REF:NUXT-RULES` → `./engineering/nuxt-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-NUXT", path: "./playbooks/nuxt-app.md",      desc: "Nuxt app playbook"}
+  - {code: "REF:NUXT-RULES",    path: "./engineering/nuxt-rules.md",  desc: "Nuxt engineering rules"}
+
+routing_entries:
+  - "Nuxt page / component task → [Nuxt App Playbook](./playbooks/nuxt-app.md)"
+
+rules:
+  - {file: rules/frontend.md, globs: ["src/frontend/**/*.{vue,ts}"]}
+
+makefile_targets:
+  - {name: lint-frontend,  cmd: "npx --yes eslint . && cd src/frontend && npm run lint"}
+  - {name: test-frontend,  cmd: "cd src/frontend && npm test"}
+  - {name: build-frontend, cmd: "cd src/frontend && npm run build"}
+
+verify:
+  - {glob: "src/frontend/**/*.{vue,ts}", suites: "lint-frontend + test-frontend", cmd: "npx --yes eslint . && cd src/frontend && npm run lint && npm test"}
+
+dimensions:
+  - {name: "Nuxt page / route",   read_files: ["docs/playbooks/nuxt-app.md", "docs/engineering/nuxt-rules.md"]}
+  - {name: "Vue component",       read_files: ["docs/engineering/nuxt-rules.md"]}
+  - {name: "Composable / state",  read_files: ["docs/playbooks/nuxt-app.md"]}
+
+skill_enforcement:
+  - {globs: ["src/frontend/**/*.{vue,ts}"], primary: vue-nuxt, secondary: [clean-code, frontend-fundamentals, frontend-design, a11y, performance, testing-strategy]}
+  - {globs: ["src/frontend/**/composables/**/*.ts", "src/frontend/**/stores/**/*.ts"], primary: vue-nuxt, secondary: [state-management, clean-code, frontend-fundamentals]}

templates/wordpress/rules/backend.md

@@ -0,0 +1,19 @@
+---
+globs: ["src/backend/**/*.php"]
+alwaysApply: false
+---
+
+# WordPress Backend Rules (auto-loaded on src/backend/**/*.php)
+
+When editing any PHP file under `src/backend/` in a WordPress project, follow these standards:
+
+- **Theme vs plugin** — behavior and data live in the plugin; the theme is presentation only. Business logic in a theme is a review finding.
+- **Sanitize on input, escape on output** — always, at every boundary. A raw `$_POST`/`$_GET` value never reaches the DB or the page unescaped.
+- **Nonce + capability** — every state change verifies a nonce and a `current_user_can()` capability; no privileged action trusts the request alone.
+- **Prepared queries** — `$wpdb->prepare()` for every query with input; never interpolate a variable into SQL.
+- **No direct file access** — guard every PHP file with `if (!defined('ABSPATH')) exit;`.
+- **Namespaced hooks/options** — prefix hooks, options, and globals with the project slug so two plugins never collide.
+
+Canonical policy: `docs/engineering/wordpress-rules.md`
+Playbook: `docs/playbooks/wordpress-service.md`
+Primary skill: `wordpress`

templates/wordpress/scaffold/docs/engineering/wordpress-rules.md

@@ -0,0 +1,28 @@
+<!-- domain:BACKEND | layer:rules | ssot:true | updated:{{DATE}} -->
+# WordPress Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} WordPress backend.
+Read when: Editing anything under `src/backend/`.
+Skip when: Frontend/mobile work.
+Read next: [WordPress Playbook](../playbooks/wordpress-service.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Theme vs plugin** — behavior and data live in the plugin; the theme is
+   presentation only.
+2. **Sanitize on input, escape on output** — always, at every boundary. A raw
+   superglobal reaching a query or an echo is a build-blocking finding.
+3. **Nonce + capability** — every state change verifies a nonce; every
+   privileged action checks `current_user_can`.
+4. **Prepared queries** — `$wpdb->prepare()` for every query with input; never
+   string-interpolate.
+5. **No direct file access** — guard PHP files with `if (!defined('ABSPATH')) exit;`.
+6. **Namespaced hooks/options** — prefix everything with the project slug to
+   avoid collisions with other plugins.
+
+## Testing bar
+
+REST routes ≥ happy + permission-denied path; security-sensitive callbacks
+tested for nonce/capability rejection.

templates/wordpress/scaffold/docs/playbooks/wordpress-service.md

@@ -0,0 +1,29 @@
+<!-- domain:BACKEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# WordPress Playbook
+
+Purpose: The end-to-end recipe for adding or changing WordPress behavior in {{PROJECT_NAME}}.
+Read when: Any task that adds a hook, shortcode, REST route, template, or custom table.
+Skip when: Pure infra/devops work — see the deployment docs.
+Read next: [WordPress Engineering Rules](../engineering/wordpress-rules.md), [Error Format](../api-contracts/error-format.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add behavior (the only sanctioned path)
+
+1. **Decide theme vs plugin** — presentation → theme; behavior/data → plugin
+   (portable, survives a theme swap).
+2. **Hook in** — `add_action`/`add_filter` with a named callback; never inline
+   anonymous logic you cannot test.
+3. **Sanitize on input** — `sanitize_text_field`, `absint`, etc. on every
+   request value before use.
+4. **Verify intent** — nonce-check (`wp_verify_nonce`) every state change and
+   capability-check (`current_user_can`) every privileged action.
+5. **Escape on output** — `esc_html`, `esc_attr`, `esc_url` at every echo.
+6. **Data** — `$wpdb->prepare()` for every query; never interpolate input.
+7. **Verify** — `cd src/backend && composer lint`.
+
+## Anti-patterns
+
+- Business logic in the theme — it dies on a theme swap; put it in the plugin.
+- Unsanitized `$_GET`/`$_POST` reaching a query — SQL injection.
+- A state-changing endpoint without a nonce + capability check — CSRF / privilege escalation.

templates/wordpress/scaffold/src/backend/composer.json

@@ -0,0 +1,17 @@
+{
+  "name": "coding-os/wordpress-scaffold",
+  "description": "WordPress plugin + theme scaffold (coding-os)",
+  "type": "project",
+  "license": "MIT",
+  "require": {
+    "php": ">=8.2"
+  },
+  "require-dev": {
+    "squizlabs/php_codesniffer": "^3.10",
+    "phpunit/phpunit": "^11.0"
+  },
+  "scripts": {
+    "lint": "phpcs",
+    "test": "phpunit"
+  }
+}

templates/wordpress/scaffold/src/backend/phpcs.xml.dist

@@ -0,0 +1,11 @@
+<?xml version="1.0"?>
+<!-- WordPress plugin + theme lint baseline (coding-os): PHP_CodeSniffer, PSR-12. -->
+<ruleset name="wordpress-scaffold">
+  <description>PHP_CodeSniffer baseline — PSR-12 (WordPress plugin + theme).</description>
+  <file>plugin</file>
+  <file>theme</file>
+  <arg name="colors"/>
+  <arg value="sp"/>
+  <rule ref="PSR12"/>
+  <exclude-pattern>*/vendor/*</exclude-pattern>
+</ruleset>

templates/wordpress/scaffold/src/backend/phpunit.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true">
+  <testsuites>
+    <testsuite name="plugin">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+</phpunit>

templates/wordpress/scaffold/src/backend/plugin/inc/health.php

@@ -0,0 +1,8 @@
+<?php
+
+declare(strict_types=1);
+
+function cos_health_status(): array
+{
+    return ['status' => 'ok'];
+}

templates/wordpress/scaffold/src/backend/plugin/plugin.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * Plugin Name: {{PROJECT_NAME}}
+ * Description: {{PROJECT_NAME}} business logic — portable across themes.
+ * Version: 0.1.0
+ * Requires PHP: 8.2
+ */
+
+declare(strict_types=1);
+
+if (!defined('ABSPATH')) {
+    exit; // No direct access.
+}
+
+require_once __DIR__ . '/inc/health.php';
+
+// Register a namespaced REST route. Sanitize on input, escape on output,
+// and permission-check every callback (return true here = public read).
+add_action('rest_api_init', static function (): void {
+    register_rest_route('{{PROJECT_NAME}}/v1', '/health', [
+        'methods' => 'GET',
+        'permission_callback' => '__return_true',
+        'callback' => static function (): WP_REST_Response {
+            return new WP_REST_Response(cos_health_status(), 200);
+        },
+    ]);
+});

templates/wordpress/scaffold/src/backend/tests/HealthStatusTest.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+require_once __DIR__ . '/../plugin/inc/health.php';
+
+final class HealthStatusTest extends TestCase
+{
+    public function test_health_status_reports_ok(): void
+    {
+        self::assertSame('ok', cos_health_status()['status']);
+    }
+}

templates/wordpress/scaffold/src/backend/theme/functions.php

@@ -0,0 +1,18 @@
+<?php
+
+// Theme bootstrap — hooks + asset enqueue only. No business logic here
+// (that belongs in the plugin so it survives a theme swap).
+
+add_action('after_setup_theme', static function (): void {
+    add_theme_support('title-tag');
+    add_theme_support('post-thumbnails');
+});
+
+add_action('wp_enqueue_scripts', static function (): void {
+    wp_enqueue_style(
+        '{{PROJECT_NAME}}-style',
+        get_stylesheet_uri(),
+        [],
+        wp_get_theme()->get('Version')
+    );
+});

templates/wordpress/scaffold/src/backend/theme/style.css

@@ -0,0 +1,11 @@
+/*
+Theme Name: {{PROJECT_NAME}}
+Theme URI:
+Author:
+Description: {{PROJECT_NAME}} theme — presentation only; business logic lives in the plugin.
+Version: 0.1.0
+Requires at least: 6.4
+Requires PHP: 8.2
+License: GPL-2.0-or-later
+Text Domain: {{PROJECT_NAME}}
+*/

templates/wordpress/scaffold-boundary.yaml

@@ -0,0 +1,23 @@
+# Scaffold boundary for the wordpress stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: wordpress
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.php"
+  - "src/backend/**/*.css"
+
+imports_from:
+  - src/shared/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Business logic in the plugin (portable); the theme is presentation only."
+  - "Sanitize on input, escape on output; nonce-verify every state change."

templates/wordpress/skills/wordpress/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: wordpress
+tier: stack
+domain: [backend]
+description: Build secure WordPress plugins and themes the WordPress way — hooks (actions/filters), nonces, capability checks, sanitize-on-input/escape-on-output, $wpdb->prepare, proper script enqueuing, and the REST API. Use when writing or reviewing a plugin/theme, hardening WP request handling, hooking into core, registering a block or REST route, or fixing "the plugin is insecure". Targets WordPress 6.x+ on PHP 8.3+. Triggers — "WordPress", "WP plugin", "theme", "add_action", "wpdb", "nonce", "shortcode", "Gutenberg block", "the loop". Pairs with php (the language), security-web (OWASP), sql-authoring (queries behind $wpdb).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# WordPress
+
+WordPress has its own way of doing everything, and fighting it produces brittle, insecure code. Three WP-specific disciplines carry most of the safety: **nonces** (intent), **capability checks** (authorization), and **sanitize-in / escape-out** (data). The PHP language craft is owned by [php](../php/SKILL.md); this is the WordPress layer on top.
+
+> Scan a plugin/theme for the WordPress security footguns:
+> `python3 scripts/scan_wp_smells.py wp-content/plugins/myplugin/**/*.php`
+
+## Hooks — the entire extension model
+
+```php
+// actions DO something; filters TRANSFORM and must return
+add_action('init', 'myplugin_register');
+add_filter('the_content', function (string $content): string {
+    return $content . '<p>Appended.</p>';   // a filter MUST return the value
+});
+```
+
+You extend WordPress by hooking, never by editing core. An `add_filter` callback
+that forgets to `return` silently blanks the content. Register everything on the
+right hook (`init`, `wp_enqueue_scripts`, `rest_api_init`) — running too early
+means core isn't loaded yet. Detail → [references/wp-development.md](references/wp-development.md).
+
+## The security trinity (every request handler)
+
+```php
+function myplugin_save(): void {
+    // 1. NONCE — the request came from your form, not a forged one
+    if (!isset($_POST['_wpnonce']) || !wp_verify_nonce($_POST['_wpnonce'], 'myplugin_save')) {
+        wp_die('Bad nonce');
+    }
+    // 2. CAPABILITY — this user is allowed to do this
+    if (!current_user_can('edit_posts')) {
+        wp_die('Forbidden');
+    }
+    // 3. SANITIZE input, ESCAPE output
+    $title = sanitize_text_field($_POST['title'] ?? '');
+    update_post_meta($post_id, 'title', $title);
+}
+```
+
+All three, every time. A nonce without a capability check stops forgery but not
+an under-privileged user; a capability check without a nonce is CSRF-able;
+neither without sanitizing is injection. Detail → [references/wp-security.md](references/wp-security.md).
+
+## Database — `$wpdb->prepare`, always
+
+```php
+global $wpdb;
+// Wrong — SQL injection
+$wpdb->query("SELECT * FROM {$wpdb->posts} WHERE post_author = {$_GET['id']}");
+
+// Correct — prepare() binds the placeholders
+$rows = $wpdb->get_results(
+    $wpdb->prepare("SELECT * FROM {$wpdb->posts} WHERE post_author = %d", $_GET['id'])
+);
+```
+
+`$wpdb->prepare` with `%d`/`%s`/`%f` placeholders is WordPress's parameterization.
+Use `$wpdb->posts` (table prefix-aware), never a hardcoded `wp_posts`. Prefer the
+high-level APIs (`WP_Query`, `get_posts`, `update_post_meta`) over raw `$wpdb`
+when they fit — they handle escaping and caching.
+
+## Enqueue scripts/styles — never hardcode `<script>`
+
+```php
+add_action('wp_enqueue_scripts', function (): void {
+    wp_enqueue_script('myplugin', plugins_url('app.js', __FILE__), ['wp-element'], '1.0.0', true);
+    wp_localize_script('myplugin', 'MyPlugin', ['nonce' => wp_create_nonce('wp_rest')]);
+});
+```
+
+`wp_enqueue_script/style` handles dependencies, versioning (cache-busting), and
+de-duplication; a raw `<script>` tag in a template breaks all three. Pass data to
+JS via `wp_localize_script`, not inline `echo`.
+
+## REST API + blocks
+
+Register routes on `rest_api_init` with a `permission_callback` (returning a
+capability check — **never** `__return_true` for anything sensitive). Gutenberg
+blocks register via `register_block_type` + `block.json`; server-rendered blocks
+escape output the same as any template.
+
+## Anti-patterns (reject on sight)
+
+- A handler with no `wp_verify_nonce` → CSRF.
+- A handler with no `current_user_can` → privilege escalation.
+- Raw `$_POST`/`$_GET` into `$wpdb->query` or output → injection / XSS.
+- `esc_html`/`sanitize_*` skipped → XSS / stored injection.
+- Hardcoded `wp_` table prefix instead of `$wpdb->posts`/`$wpdb->prefix`.
+- `<script>`/`<link>` in a template instead of `wp_enqueue_*`.
+- REST route with `'permission_callback' => '__return_true'` on sensitive data.
+- Editing core or a parent theme instead of hooks / a child theme.
+
+## See also
+
+- [references/wp-development.md](references/wp-development.md) — hooks, enqueue, the loop, REST, blocks, plugin/theme structure.
+- [references/wp-security.md](references/wp-security.md) — nonces, capabilities, sanitize/escape function map, $wpdb.
+- [assets/wp-checklist.md](assets/wp-checklist.md) — the review gate.
+- [php](../php/SKILL.md) · [security-web](../security-web/SKILL.md) · [sql-authoring](../sql-authoring/SKILL.md).

templates/wordpress/skills/wordpress/assets/wp-checklist.md

@@ -0,0 +1,28 @@
+<!-- domain:BACKEND | layer:asset | ssot:false | updated:2026-06-04 -->
+# WordPress Plugin/Theme Review Checklist
+
+Run before shipping a plugin or theme.
+
+## The security trinity (every request handler)
+- [ ] Nonce verified (`wp_verify_nonce`/`check_admin_referer`/`check_ajax_referer`).
+- [ ] Capability checked (`current_user_can('<cap>')`) — not a role name.
+- [ ] Input sanitized (`sanitize_text_field`/`absint`/`wp_kses_post`).
+- [ ] Output escaped for context (`esc_html`/`esc_attr`/`esc_url`).
+
+## Database
+- [ ] Every `$wpdb` query uses `->prepare()` with `%d`/`%s`/`%f`.
+- [ ] Table names via `$wpdb->prefix`/`$wpdb->posts` — never hardcoded `wp_`.
+- [ ] High-level APIs (`WP_Query`, `get_post_meta`) preferred over raw SQL.
+
+## WordPress way
+- [ ] Extends via hooks; no core / parent-theme edits (child theme used).
+- [ ] Filters always `return`; callbacks on the correct hook.
+- [ ] Assets via `wp_enqueue_*` (versioned), data via `wp_localize_script`.
+- [ ] `wp_reset_postdata()` after every secondary loop.
+- [ ] REST routes have a real `permission_callback` (never `__return_true` on sensitive data).
+- [ ] Unique prefix/namespace on functions, options, meta keys.
+
+## Verify
+- [ ] `python3 scripts/scan_wp_smells.py <plugin php files>` → `clean`.
+- [ ] PHPCS with the WordPress-Extra ruleset — clean.
+- [ ] `make skills-check-versions` — WordPress/PHP pins current.

templates/wordpress/skills/wordpress/references/wp-development.md

@@ -0,0 +1,75 @@
+<!-- domain:BACKEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# WordPress Development — Hooks, Enqueue, Loop, REST, Blocks
+
+> P: Build plugins/themes the WordPress way so code survives core updates.
+> R: Writing a plugin/theme, registering a route/block, or rendering content.
+> S: Security specifics — see [wp-security.md](wp-security.md).
+> N: [SKILL.md](../SKILL.md), [wp-checklist.md](../assets/wp-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Actions vs filters
+
+| | Action | Filter |
+|---|---|---|
+| purpose | DO something (side effect) | TRANSFORM a value |
+| returns | nothing | the (modified) value — ALWAYS |
+| example | `add_action('init', $fn)` | `add_filter('the_title', $fn)` |
+
+A filter callback that doesn't `return` blanks the value it was given — the most
+common WordPress bug. Hook priority (3rd arg) orders callbacks; accepted-args
+(4th) controls how many params core passes.
+
+## Plugin/theme structure
+
+```
+my-plugin/
+├── my-plugin.php        # header comment + bootstrap (hooks only, no logic dump)
+├── includes/            # classes, autoloaded
+├── assets/              # js/css (enqueued, never inline)
+└── languages/           # i18n .pot/.po
+```
+
+Use a child theme to customize a theme (never edit the parent — updates wipe it).
+Namespacing or a unique prefix on every function/option/meta key avoids
+collisions with other plugins.
+
+## The loop + WP_Query
+
+```php
+$q = new WP_Query(['post_type' => 'book', 'posts_per_page' => 10]);
+while ($q->have_posts()) { $q->the_post(); the_title('<h2>', '</h2>'); }
+wp_reset_postdata();   // ALWAYS reset after a custom query
+```
+
+Prefer `WP_Query`/`get_posts` over raw `$wpdb` — they cache and escape. Always
+`wp_reset_postdata()` after a secondary loop or the global `$post` stays wrong.
+
+## Enqueue (the only way to load assets)
+
+```php
+add_action('wp_enqueue_scripts', function (): void {
+  wp_enqueue_style('mp', plugins_url('app.css', __FILE__), [], '1.0.0');
+  wp_enqueue_script('mp', plugins_url('app.js', __FILE__), [], '1.0.0', true);  // true = footer
+});
+```
+
+`wp_enqueue_*` dedupes, versions (cache-bust), and resolves dependencies. Pass
+PHP→JS data with `wp_localize_script` / `wp_add_inline_script`, never `echo` into
+a `<script>`.
+
+## REST API + blocks
+
+```php
+add_action('rest_api_init', function (): void {
+  register_rest_route('myplugin/v1', '/items', [
+    'methods'  => 'GET',
+    'callback' => 'myplugin_items',
+    'permission_callback' => fn() => current_user_can('read'),   // never __return_true on sensitive data
+  ]);
+});
+```
+
+Blocks register with `register_block_type(__DIR__ . '/build')` reading
+`block.json` (the SSOT for a block's metadata). Server-rendered blocks escape
+output exactly like a template.

templates/wordpress/skills/wordpress/references/wp-security.md

@@ -0,0 +1,68 @@
+<!-- domain:BACKEND | layer:reference | ssot:true | updated:2026-06-04 -->
+# WordPress Security — Nonces, Capabilities, Sanitize/Escape, $wpdb
+
+> P: The WordPress-specific defensive functions and exactly when each applies.
+> R: Handling any request, output, or database access in a plugin/theme.
+> S: General OWASP / PHP-language security — [security-web](../../security-web/SKILL.md) + [php](../../php/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [wp-development.md](wp-development.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Nonces — prove intent (anti-CSRF)
+
+```php
+// in the form
+wp_nonce_field('myplugin_save', '_wpnonce');
+// in the handler
+check_admin_referer('myplugin_save');     // dies on failure (admin forms)
+// AJAX
+check_ajax_referer('myplugin_ajax', 'nonce');
+```
+
+A nonce ties a request to a user + action + short time window — it stops a forged
+cross-site request. It is **not** authorization (see capabilities) and not a
+replacement for sanitizing.
+
+## Capabilities — prove authorization
+
+```php
+if (!current_user_can('manage_options')) { wp_die('Forbidden'); }
+```
+
+Check the **capability** (`edit_posts`, `manage_options`, `delete_users`), never
+the role name — capabilities are the stable API. For a specific object:
+`current_user_can('edit_post', $post_id)`.
+
+## Sanitize on input, escape on output
+
+| Input → sanitize | Output → escape |
+|---|---|
+| `sanitize_text_field($s)` | `esc_html($s)` (HTML body) |
+| `sanitize_email($e)` | `esc_attr($s)` (HTML attribute) |
+| `absint($n)` | `esc_url($u)` (href/src) |
+| `sanitize_key($k)` | `esc_js($s)` (inline JS) |
+| `wp_kses_post($html)` (allow safe HTML) | `wp_kses($html, $allowed)` |
+
+Sanitize when you store; escape when you render, for the **context**. `wp_kses`
+is for "allow some HTML" (a comment body); `esc_html` is for "allow none". Never
+trust data even from the database — escape on output regardless of source.
+
+## $wpdb — prepare everything
+
+```php
+$wpdb->get_results(
+  $wpdb->prepare("SELECT * FROM {$wpdb->prefix}orders WHERE status = %s AND total > %d",
+                 $status, $min)
+);
+```
+
+`%s` (string), `%d` (int), `%f` (float). The table name uses `$wpdb->prefix` /
+`$wpdb->posts` (multisite + custom-prefix safe). Prefer `WP_Query`,
+`get_post_meta`, `get_option` over raw SQL — they escape and cache for free.
+
+## Options & meta
+
+`update_option`/`get_option` and `update_post_meta`/`get_post_meta` store data —
+sanitize before storing, escape on output. Register settings with a
+`sanitize_callback` so the Settings API enforces it. Never store secrets in an
+autoloaded option (loads on every request).