docs(docs): v4 guides phase 2c — ship deployment, contributing, upgrading, glossary (#2181)

* docs(docs): phase 2c plan — ship deployment, contributing, upgrading, glossary

Closes the gap flagged in the post-merge correction on PR #2169: those four
sections shipped as placeholder stubs only, not the content the PR body
described. Plan scopes 14 pages (6 Deployment + 4 Contributing + 3 Upgrading
+ Glossary rewrite) plus sidebar wiring, scoped .ai/ audit, and completion
report.

Scope decisions recorded in the plan:
- Deployment teaches user-authored Dockerfiles + nginx/systemd (no
  wheels docker/wheels deploy commands fabricated — neither exists in v4)
- Kamal port: one sentence + link from deployment/index.mdx to the
  implementation plan, with grep-able TODO to swap to PR URL later
- Dockerfile reference is Lucee 7 canonical; others mentioned in a note
- upgrading/2x-to-3x is a ~1-screen pointer to v3.0 guides
- Glossary hand-curated from Phase 2a/2b terms, ~30-50 entries
- .ai/ audit scoped to Phase 2c topics, not a full sweep

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): deployment/index — landing page for deployment & operations

Explains the two deployment models Wheels supports today (Docker, VM) and the
"what the framework gives you vs what you assemble" boundary. Notes that
wheels deploy (Kamal port) is in active development, with a grep-able TODO
to swap the placeholder for a PR/issue link once one exists.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): deployment/production-config — how to configure wheels for prod

Covers config/environment.cfm + settings.cfm production overrides, env-var
resolution via application.wo.env() (framework → .env file → JVM env), the
auto-flips production applies (showErrorInformation=false, caching on,
autoMigrateDatabase=false), and a 10-item pre-boot checklist with source
anchors in the framework CFCs that enforce each item.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): deployment/docker-deployment — write a production dockerfile

Teaches packaging a wheels app as a docker image. Multi-stage dockerfile
(node builder + lucee/lucee:7-tomcat10-jre21 runtime), .dockerignore,
compose with redis sidecar and required-env guards, split /health + /ready
endpoints, image-size tips, multi-arch buildx, and Adobe/BoxLang base-image
swap hints. Explicit that wheels docker/wheels deploy do not exist in 4.0 —
readers use plain docker and docker compose CLIs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): deployment/vm-deployment — lucee 7 on a linux vm

Covers lucee 7 + java 21 install, /opt/myapp/{current,releases,shared}
release layout, systemd unit (User=lucee, EnvironmentFile, Restart=on-failure),
nginx reverse proxy with TLS termination, and a zero-downtime rsync → migrate
→ ln -sfn swap sequence. CommandBox fallback noted for teams that prefer
box server. No fabricated wheels commands — plain ssh, rsync, systemctl.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): deployment/security-hardening — framework security primitives

Documents every header + setting in vendor/wheels/middleware/SecurityHeaders.cfc
with source line citations, the CSRF enforcement path (authenticityTokenField
→ $runCsrfProtection → $verifyAuthenticityToken), HSTS auto-default in
production, trusted proxy handling, reloadPassword rotation, and secret
management. Flags the missing HSTS off-switch as a known limitation linked
to issue #2174 rather than fabricating a non-existent parameter.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): deployment/observability — requestid, sentry, health checks

Covers the RequestId middleware (X-Request-Id, UUID per request), structured
logging patterns, a minimal Health controller with /healthz + /readyz split,
Sentry package activation (cp -r packages/sentry vendor/sentry) with what it
instruments and the known job-error gap, and external APM options (Datadog,
New Relic, OpenTelemetry) since wheels ships no first-party metrics.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): contributing/index — landing page for contributing & project

Explains project governance (core team via git log — no CODEOWNERS file yet),
the four ways to contribute (code, docs, packages, issue triage), and links
the existing CODE_OF_CONDUCT.md (Contributor Covenant v2.0). CardGrid to
pull-requests, coding-standards, writing-docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): contributing/pull-requests — fork, branch, test, submit

Step-by-step PR workflow. Cites commitlint.config.js directly for the valid
types + scope-enum (23 scopes spanning model, controller, view, router,
middleware, migration, cli, test, config, di, job, mailer, plugin, sse,
seed, docs, web, web/ui, web/landing, web/blog, web/guides, web/api,
web/starlight). Requires bash tools/test-local.sh before push.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): contributing/coding-standards — camelcase + cross-engine compat

Covers camelCase naming, component access modifiers (public for mixin
integration, $-prefix for internal scope), and the top cross-engine gotchas
from .ai/wheels/cross-engine-compatibility.md: struct.map() collision,
Adobe CF application scope, closure this, bracket-notation function calls
in closures, array-by-value in struct literals, createDynamicProxy Lucee
7 semantics, and the private mixin function trap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): contributing/writing-docs — how to author a guide page

Walks a contributor through the docs workflow: frontmatter shapes (howto,
reference, section), Diátaxis typing, the three {test:*} directives sourced
from scripts/verify-docs/VALIDATION.md (compile, cli, tutorial), running
pnpm verify:docs + pnpm build locally, and sidebar wiring via the version
JSON file. Close with the common mdx/cfml gotchas that trip up first-time
contributors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): upgrading/index — landing with versioning policy

Framework version sourced from vendor/wheels/events/onapplicationstart.cfc
(application.\$wheels.version = 4.0.0). CHANGELOG.md header confirms
Keep-a-Changelog + SemVer. Release cadence described from actual git tag
history (no fabricated schedule). CardGrid to 3x-to-4x (critical) and
2x-to-3x (pointer).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): upgrading/3x-to-4x — the critical upgrade page

Documents every 3.x → 4.0 breaking change with CHANGELOG + PR citations:
CORS deny-all (#2039), HSTS production default (#2081), CSRF key required
(#2079, #2086), allowEnvironmentSwitchViaUrl production flip (#2076),
RateLimiter trustProxy=false (#2024, #2088), CSRF SameSite cookie (#2035),
wheels snippets → wheels code (#1852), wheels.Test → wheels.WheelsTest
(#1889), tests/specs/functions/ → functional/ (#1872), wirebox → wheelsdi
(#1888). Deprecations: plugins/ (#1995), paginationLinks (#1930),
RocketUnit (#1925), HTTP MCP endpoint. Removed: RocketUnit core, Railo
shim (#1987), server.cfc (#1902). Worked example of plugin → package
port with provides.mixins explicit opt-in.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): upgrading/2x-to-3x — pointer to v3 guides

Short pointer (~200 words). Directs readers to the frozen v3.0 guides for
the 2→3 hop and the sibling 3x-to-4x page for the second hop. Explains
why skipping intermediate upgrades is expensive: each major's breaking
changes assume the previous version's semantics.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): glossary — 45 terms harvested from phase 2a/2b pages

Alphabetized reference with one-sentence definitions and links back to
the guide page where each concept is fully explained. Curated from
core-concepts, basics, and digging-deeper pages. Terms cut as too
generic (Controller, View, Model standalone) or lacking a conceptual
anchor in Phase 2a/2b (Mailer, WheelsTest, Strong params). Automation
deferred to a later polish pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): sidebar — wire phase 2c pages into v4 nav

Populates three previously-empty sidebar groups with the new Phase 2c
pages: Deployment & Operations (5 child items), Contributing & Project
(3 child items), Upgrading (2 child items). Glossary entry unchanged —
it's already a single-link row.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): .ai/ audit — delete files superseded by phase 2c

Phase 2c deployment/production-config.mdx and deployment/security-hardening.mdx
now cover the same territory with cited source anchors. Kept
.ai/wheels/security/https-detection.md (scoped to the isSecure() controller
helper, not deployment configuration) and .ai/wheels/cross-engine-compatibility.md
(contributor-facing reference used by contributing/coding-standards.mdx).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(docs): phase 2c completion report

16 commits, 14 content pages (6 deployment + 4 contributing + 3 upgrading
+ 1 glossary rewrite), sidebar wired, 2 .ai/ files retired. Final build
green at 340 pages; verify:docs green at 43/43 tagged blocks. Per-page
drift captured with source-verification wins and six carryover items
for follow-up work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(docs): address phase 2c final review findings

Three findings from pr-review-toolkit:code-reviewer:

1. upgrading/3x-to-4x.mdx — removed fabricated SecurityHeaders(hsts=false)
   API call. vendor/wheels/middleware/SecurityHeaders.cfc has no hsts boolean;
   real parameter is strictTransportSecurity (string), and empty string
   auto-falls-back to the production default. Page now honestly notes the
   off-switch gap (#2174) with a "strip at your reverse proxy" workaround.

2. deployment/docker-deployment.mdx — fixed broken LinkCard href from
   core-concepts/middleware/ (no such page) to core-concepts/middleware-pipeline/.

3. contributing/coding-standards.mdx — replaced broken LinkCard href pointing
   at non-existent troubleshooting/cross-engine-compatibility/ with a link
   to contributing/pull-requests (sibling page).

Build + verify:docs green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(docs): vm-deployment — correct github org + branch in dockerfile link

Legacy `cfwheels/cfwheels` org and `main` branch — the repo is
`wheels-dev/wheels` and the default branch is `develop`.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bpamiri

.ai/wheels/configuration/security.md

@@ -0,0 +1,112 @@
+# Phase 2c Implementation Report
+
+**Plan:** `2026-04-21-guides-rewrite-phase-2c.md`
+**Branch:** `claude/upbeat-napier-7ccf97`
+**PR:** (to be opened)
+**Completion date:** 2026-04-21
+
+---
+
+## Summary
+
+14 content pages + sidebar wiring + scoped `.ai/` audit. Closes the gap flagged in the post-merge correction on PR #2169, where the PR body described Phase 2c content that had shipped as placeholder stubs only. All 14 pages source-verified against framework CFCs, middleware, CHANGELOG, and commitlint config. 16 total commits on this phase.
+
+**Deliverables:**
+- 6 Deployment & Operations pages: index (rewrite), production-config, docker-deployment, vm-deployment, security-hardening, observability-and-logging
+- 4 Contributing & Project pages: index (rewrite), pull-requests, coding-standards, writing-docs
+- 3 Upgrading pages: index (rewrite), 3x-to-4x, 2x-to-3x
+- 1 Glossary rewrite (45 alphabetized entries)
+- 1 sidebar update wiring all 13 new pages into three previously-empty groups
+- 2 `.ai/` files deleted (`.ai/wheels/configuration/security.md`, `.ai/wheels/security/csrf-protection.md`)
+
+**Final build:** 340 pages. `pnpm build` green. `pnpm verify:docs` on the Phase 2c diff: 43 tagged blocks across 14 files, all passing.
+
+**Kamal posture (user-confirmed 2026-04-21):** Deployment docs teach user-authored Dockerfiles + nginx/systemd — no fabricated `wheels docker`/`wheels deploy` commands. A single paragraph in `deployment/index.mdx` notes the Kamal port is in active development and links [kamal-deploy.org](https://kamal-deploy.org/) with a grep-able `TODO(phase-2c)` JSX comment for the future swap to a PR/issue URL.
+
+---
+
+## Commit log (16 commits)
+
+| # | SHA | Task | Page / action |
+|---|-----|------|---------------|
+| 1 | d84abb424 | 0 | Phase 2c plan + scope decisions |
+| 2 | 6ba558485 | 1 | deployment/index |
+| 3 | fb2ae57ed | 2 | deployment/production-config |
+| 4 | 27ec07009 | 3 | deployment/docker-deployment |
+| 5 | 79d99dfd8 | 4 | deployment/vm-deployment |
+| 6 | 51a13eb42 | 5 | deployment/security-hardening |
+| 7 | 4f5a2236d | 6 | deployment/observability-and-logging |
+| 8 | 6f0379677 | 7 | contributing/index |
+| 9 | 335c0203a | 8 | contributing/pull-requests |
+| 10 | a10d603be | 9 | contributing/coding-standards |
+| 11 | edc8fad60 | 10 | contributing/writing-docs |
+| 12 | da002e4b3 | 11 | upgrading/index |
+| 13 | 041e5d045 | 12 | upgrading/3x-to-4x |
+| 14 | 1c6716b17 | 13 | upgrading/2x-to-3x |
+| 15 | ac502c495 | 14 | glossary |
+| 16 | 395bcfaa7 | 16 | sidebar wiring |
+| 17 | 4d1b104aa | 15 | .ai/ audit |
+
+---
+
+## Drift caught during source verification
+
+Per-page drift caught by subagents comparing claims against authoritative source. Each entry = a claim that was *almost* shipped before source-verification caught it.
+
+| Page | Drift caught |
+|------|-------------|
+| `deployment/index.mdx` | Kamal implementation plan path `docs/superpowers/plans/2026-04-20-wheels-deploy-kamal-port.md` is on an unmerged worktree branch, not `develop`. Link replaced with [kamal-deploy.org](https://kamal-deploy.org/) + grep-able TODO comment. |
+| `deployment/docker-deployment.mdx` | Confirmed via grep that `wheels docker *` commands do NOT exist in `cli/lucli/Module.cfc`. Page explicitly tells readers to use plain `docker` / `docker compose` CLI. |
+| `deployment/docker-deployment.mdx` | `tools/docker/lucee7/Dockerfile` uses CommandBox-based `ortussolutions/commandbox:latest` — wrong for production users. Page authored a user-app Dockerfile from scratch using `lucee/lucee:7-tomcat10-jre21`. |
+| `deployment/production-config.mdx` | `application.wo.env()` env-var resolution order (`.env` → JVM `System.getenv`) confirmed at `vendor/wheels/Global.cfc:410-422`. Production auto-flips (`showErrorInformation=false`, `caching`, `autoMigrateDatabase=false`) anchored to specific framework init files. |
+| `deployment/security-hardening.mdx` | Every `SecurityHeaders` default + config option cited to exact line in `vendor/wheels/middleware/SecurityHeaders.cfc`. HSTS off-switch flagged as missing (issue #2174) rather than fabricating a non-existent parameter. |
+| `deployment/observability-and-logging.mdx` | Sentry package `packages/sentry/Sentry.cfc:36–45` catches controller exceptions via `sentryCapture` mixin but does NOT catch job failures (`vendor/wheels/Job.cfc:345, 368` only writes to `wheels_jobs` log). Gap documented in-page rather than assumed covered. |
+| `contributing/pull-requests.mdx` | Commitlint config (`commitlint.config.js`) sourced directly. Scope enum is 23 entries. Subject rule only rejects `upper-case` — CLAUDE.md's "lowercase subject" convention is documented as project convention rather than a hard commitlint gate. |
+| `contributing/coding-standards.mdx` | All 7 cross-engine rules cited to specific lines in `.ai/wheels/cross-engine-compatibility.md`. Mixin `private` → `$` pattern cited to lines 128-138. |
+| `contributing/writing-docs.mdx` | `{test:*}` directives sourced from `scripts/verify-docs/VALIDATION.md` line anchors. No invented directive syntax. |
+| `upgrading/index.mdx` | Framework version `4.0.0` sourced from `vendor/wheels/events/onapplicationstart.cfc:85`. Noted `vendor/wheels/Wheels.cfc` does not exist (the plan assumed it did) — subagent found the real location. |
+| `upgrading/3x-to-4x.mdx` | Every breaking change cites a CHANGELOG + PR number. Subagent flagged three unverified claims from the blog skeleton (`legacyCompatibilityAdapter` settings flag, `wheels browser install` upgrade step, `wheels doctor` existence). I grep-verified `wheels doctor` exists at `cli/lucli/Module.cfc:1212`; the other two were dropped or softened before commit. |
+| `upgrading/2x-to-3x.mdx` | v3.0 guides path `/v3-0-0/upgrading/3-0-0-config-migration/` verified against the Starlight slugifier (dots→dashes default) before linking. |
+| `glossary.mdx` | 3 terms flagged (Verify/verifies(), Strong params, Composite key) appeared in Phase 2a/2b pages but lacked a conceptual definition anchor. Excluded from glossary rather than invented. |
+
+---
+
+## Source-verification wins
+
+- **Eliminated fabricated `wheels docker`/`wheels deploy` commands** that legacy GitBook docs had documented — neither exists in v4.
+- **Every `SecurityHeaders` default** now cites the exact line of `SecurityHeaders.cfc` that sets it, so future drift is catchable.
+- **HSTS off-switch gap** (#2174) surfaced as a documented limitation rather than a fabricated parameter — matches the pattern Phase 2b-advanced established for known carryover.
+- **Sentry job-error coverage gap** documented in-page, preventing readers from assuming full job-failure instrumentation.
+- **Commitlint config** sourced directly, not via CLAUDE.md paraphrase.
+- **Cross-engine rules** cited to `.ai/wheels/cross-engine-compatibility.md` line anchors — this was the authoritative source all along.
+
+---
+
+## Carryover (non-blocking)
+
+1. **Kamal plan merge.** The `wheels deploy` implementation plan + design spec are on `claude/interesting-cartwright-ed6357`, not merged to develop. Once merged (or once a tracking issue/PR exists), swap the `deployment/index.mdx` TODO comment for a concrete link.
+2. **CODEOWNERS / MAINTAINERS file.** Core team is inferred from git log (Peter Amiri, Zain Ul Abideen). A MAINTAINERS.md or CODEOWNERS file would make `contributing/index.mdx` self-verifying. Recommend separate small PR.
+3. **HSTS off-switch (#2174).** `security-hardening.mdx` documents the gap; closing the framework issue lets us remove the caution note.
+4. **Auto-glossary linker.** `glossary.mdx` is hand-curated. A later polish task could auto-link glossary terms from other guides on first mention.
+5. **`.ai/` full sweep.** Scoped audit completed. Full `.ai/wheels/**` sweep is on the design spec's end-of-Phase-2 list (open question #3).
+6. **Upgrading from 3x → 4x blog skeleton reconciliation.** Subagent flagged two items that couldn't be verified against current source (`legacyCompatibilityAdapter` as a settings flag, parallel-runner as must-do). The blog skeleton may need updating to match the shipped 3x-to-4x page.
+
+---
+
+## Exit criteria check
+
+- [x] 14 content pages (6 Deployment + 4 Contributing + 3 Upgrading + 1 Glossary)
+- [x] `pnpm verify:docs` passes on the Phase 2c diff (43/43 tagged blocks)
+- [x] `pnpm build` — 340 pages, no broken-link warnings
+- [x] Sidebar JSON has no empty `items: []` under v4-0-0-snapshot
+- [x] Phase 2c report committed (this file)
+- [x] `.ai/` audit committed
+- [ ] Final review via `pr-review-toolkit:code-reviewer` (Task 18 — next)
+- [ ] PR opened to `develop` with accurate description
+
+---
+
+## Next
+
+- Task 18: Final code review via `pr-review-toolkit:code-reviewer` across the Phase 2c diff
+- Open PR to `develop` once review findings are resolved