[kriszyp]

⊙ Problem

Harper Pro features are documented in HarperFast/documentation, so a user-facing change here needs a companion docs PR and a companion-check gate. Some core reference pages also mix in Harper Pro sections, which harper-pro changes cannot edit without a harper PR.

🤔 Should Harper Pro's reference pages live here?

Proposed yes, alongside the harper PR that moves the core reference into harper. The alternative is keeping Pro pages in harper, which leaves about 10% of changes needing a companion PR.

💡 Solution

• docs/reference/replication/ and docs/reference/web-application-firewall/ move here from HarperFast/documentation, with their git history.
• Three Harper Pro sections of core pages become partials here (_pro-*.md). The core page renders each partial, and its headings, anchors and table of contents are unchanged.
• The 5.4 notes for replication and the profiler are release-note fragments here.
• A Docs workflow builds the site with this PR's docs/ and the core docs at this PR's core commit.
• core is bumped to the harper PR that adds docs/.
• A Publish Docs workflow redeploys the site on a release or a docs/ correction tag.

🔧 Changes

• Pages — docs/reference/replication/ and docs/reference/web-application-firewall/ (7 pages plus _category_.json) are the documentation repo's files at the import commit, with sidebar order moved into front matter and prettier 3.9 formatting.
• Partials — _pro-replication-operations.md and _pro-waf-operations.md are the Replication & Clustering and Web Application Firewall sections of the core Operations API page; _pro-replication-options.md is the replication section of the core configuration options page.
• Release notes — five 5.4 fragments: the Replication section and the Harper Pro profiler note. File list below.
• Guide — docs/README.md points to harper's docs guide and says how to preview with both checkouts.
• CI — docs.yaml builds the site with this PR's docs/ and the core docs at the core commit, runs on a core bump too, and fails when the site cannot assemble it yet.
• Submodule — core moves to the harper PR's head, the first core commit with docs/.
• Publishing — publish-docs.yaml runs on a published release (not a prerelease) or a docs/ tag push, and sends docs-source-changed to HarperFast/documentation with a HarperFast AI App token scoped to that repo. docs/README.md previews with just HARPER_PRO_DOCS_PATH, taking the core docs from core/.

Moved files (17)

• docs/reference/configuration/_pro-replication-options.md
• docs/reference/operations-api/_pro-replication-operations.md
• docs/reference/operations-api/_pro-waf-operations.md
• docs/reference/replication/_category_.json
• docs/reference/replication/clustering.md
• docs/reference/replication/overview.md
• docs/reference/replication/residency.md
• docs/reference/replication/sharding.md
• docs/reference/web-application-firewall/_category_.json
• docs/reference/web-application-firewall/configuration.md
• docs/reference/web-application-firewall/operations.md
• docs/reference/web-application-firewall/overview.md
• docs/release-notes/v5-lincoln/5.4/dedicated-replication-threads.md
• docs/release-notes/v5-lincoln/5.4/lmdb-replication-confirmation.md
• docs/release-notes/v5-lincoln/5.4/local-replicas-of-records-fetched-from-another-node.md
• docs/release-notes/v5-lincoln/5.4/sharding.md
• docs/release-notes/v5-lincoln/5.4/the-harper-pro-profiler-samples-in-short-windows.md

✅ Verification

• Built the documentation site with HARPER_DOCS_PATH=core and HARPER_PRO_DOCS_PATH=., as the workflow does: it succeeds, and the published pages match the current site.
• Prettier passes on docs/ and the new workflow.
• Not run: publish-docs.yaml first runs at the next published release. It relies on the HarperFast AI App being installed on HarperFast/documentation, which that repo's claude-review.yml already uses; if it is not, the step fails and the site's hourly check publishes the release.
• PR QA: skipped @ c224ff2 — docs relocation and CI only; no runtime code changes.

Paired PRs and merge order

This is one of three PRs: harper#3944 (core reference), harper-pro#1237 (Harper Pro pages) and documentation#788 (the site assembles both). Merge harper and harper-pro first, with a merge commit, then documentation. Until documentation merges, the Docs check here fails on purpose, because the site's main does not yet read docs/.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @kriszyp.}

Release target: main — moves documentation and CI only; the site publishes these docs from the first release that contains them (5.4.0)
Related PRs: #1211 overlaps (also moves the core submodule pointer; whichever merges second rebases), 1 other independent
Complexity: medium

Deferred findings

• 57f5d26f40e93d43 minor reliability — .github/workflows/docs.yaml — Unpinned documentation-site checkout — NOT FILED
• 6a204d81d0de7ba6 minor security — .github/workflows/docs.yaml — Unpinned site npm ci/build runs with the full harper-pro tree on disk — NOT FILED
• dcd34aca9c1e56b0 nit reliability — .github/workflows/docs.yaml — Path-filtered check: if required it stays pending on other PRs; if optional a red build can merge — NOT FILED
• a54e44b09caafce6 nit reliability — .github/workflows/docs.yaml — No push-to-main trigger for a post-merge docs build — NOT FILED

Late Grok findings

3 surviving (highest minor), 5 previously adjudicated — Grok reviewed 24a7dbb

• major — .github/workflows/docs.yaml:49 — The core submodule this branch pins has no docs/ tree. Once the documentation site's main branch reads HARPER_DOCS_PATH, every Docs build this workflow triggers fails before compiling a page. (previously adjudicated)
• minor — .github/workflows/docs.yaml:33 — The check can pass green without building this PR's docs at all.
• minor — .github/workflows/docs.yaml:28 — Code from the site repo runs with the whole private harper-pro source on disk.
• nit — .github/workflows/docs.yaml:33 — The site checkout passes no token. If HarperFast/documentation were private, the checkout would fail with not-found.
• nit — .github/workflows/docs.yaml:8 — With the paths: filter, the check cannot safely be required. As a required check it stays pending on every PR outside those paths; left optional, a red docs build can merge. (previously adjudicated)
• nit — .github/workflows/docs.yaml:3 — Part of the header comment describes the checkout and build steps the YAML already shows. (previously adjudicated)
• nit — docs/README.md:5 — The preview command does not say it must be run from a HarperFast/documentation checkout. (previously adjudicated)
• nit — .github/workflows/docs.yaml:8 — There is no push: main trigger, so landed changes get no build in this repo. (previously adjudicated)

Not standing: none. Grok ran 8m (8m from launch to report); the fold adjudication (cursor-grok@24a7dbbdd669-baaf2cfb, claude) took 1m.

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=5; full=2 @ c224ff2}

_{Review-Attention: study ~20m (sensitive: docs.yaml, publish-docs.yaml; decisions: core-bump-in-docs-pr, publish-dispatch-on-release-and-docs-tags, docs-build-against-site-main, operator-maintenance-snippet-in-reference) @ c224ff2}

[gemini-code-assist]

Code Review

This pull request adds comprehensive documentation and release notes for Harper Pro, focusing on replication, clustering, schema-defined sharding, and the Web Application Firewall (WAF). The feedback points out several broken markdown links across the new documentation files where the opening parenthesis of the link target was omitted. These should be fixed to ensure the documentation renders correctly.

[gemini-code-assist]

The markdown links for initialize_shard_map and verify_shard_map are broken because they are missing the opening parenthesis ( before the path. They should be formatted as [text](path).

Suggested change

The POST operations [`initialize_shard_map`](./residency.md#installed-maps) and [`verify_shard_map`](./residency.md#3-compare-placement-on-every-node) require `super_user`. The former installs a snapshot without moving records; the latter compares the actual legacy function against a proposed key policy without modifying data. Their request examples, parameters and result fields are in the linked procedures.

The POST operations [\`initialize_shard_map\`](./residency.md#installed-maps) and [\`verify_shard_map\`](./residency.md#3-compare-placement-on-every-node) require \`super_user\`. The former installs a snapshot without moving records; the latter compares the actual legacy function against a proposed key policy without modifying data. Their request examples, parameters and result fields are in the linked procedures.

[gemini-code-assist]

The markdown link for @sharded is broken because it is missing the opening parenthesis ( before the path. It should be formatted as [text](path).

Suggested change

	In v5.4, [`@sharded`](./residency.md) hashes primary keys to fixed slots on every worker. Slot counts and the installed slot map belong to the database. Attribute-derived policies and custom expressions are refused pending [concurrent-move design (#1178)](https://github.com/HarperFast/harper-pro/issues/1178).
	In v5.4, [\`@sharded\`](./residency.md) hashes primary keys to fixed slots on every worker. Slot counts and the installed slot map belong to the database. Attribute-derived policies and custom expressions are refused pending [concurrent-move design (#1178)](https://github.com/HarperFast/harper-pro/issues/1178).

[gemini-code-assist]

The markdown link for activation.regions is broken because it is missing the opening parenthesis ( before the path. It should be formatted as [text](path).

Suggested change

	This node's region for rule [`activation.regions`](./operations.md#activation) matching.
	This node's region for rule [\`activation.regions\`](./operations.md#activation) matching.

[gemini-code-assist]

The markdown link for activation.tags is broken because it is missing the opening parenthesis ( before the path. It should be formatted as [text](path).

Suggested change

	This node's tags for rule [`activation.tags`](./operations.md#activation) matching. A tag selector matches when at least one rule tag appears in this array.
	This node's tags for rule [\`activation.tags\`](./operations.md#activation) matching. A tag selector matches when at least one rule tag appears in this array.

[gemini-code-assist]

The markdown link for waf.region is broken because it is missing the opening parenthesis ( before the path. It should be formatted as [text](path).

Suggested change

	- `regions` - Matches [`waf.region`](./configuration.md#wafregion).
	- \`regions\` - Matches [\`waf.region\`](./configuration.md#wafregion).

[gemini-code-assist]

The markdown link for waf.nodeTags is broken because it is missing the opening parenthesis ( before the path. It should be formatted as [text](path).

Suggested change

	- `tags` - Matches if any listed tag appears in [`waf.nodeTags`](./configuration.md#wafnodetags).
	- \`tags\` - Matches if any listed tag appears in [\`waf.nodeTags\`](./configuration.md#wafnodetags) value.

[gemini-code-assist]

The markdown link for waf.region is broken because it is missing the opening parenthesis ( before the path. It should be formatted as [text](path).

Suggested change

	- `regions` matches [`waf.region`](./configuration.md#wafregion).
	- \`regions\` matches [\`waf.region\`](./configuration.md#wafregion).

[gemini-code-assist]

The markdown link for waf.nodeTags is broken because it is missing the opening parenthesis ( before the path. It should be formatted as [text](path).

Suggested change

	- `tags` matches when the node has at least one listed [`waf.nodeTags`](./configuration.md#wafnodetags) value.
	- \`tags\` matches when the node has at least one listed [\`waf.nodeTags\`](./configuration.md#wafnodetags) value.