Link resolution

memory/MEMORY.md

@@ -0,0 +1,77 @@
+# Documentation Migration Memory
+
+## Project Overview
+
+Harper v4 docs migration: consolidating `versioned_docs/version-4.X/` → `reference_versioned_docs/version-v4/` with feature-based reorganization.
+
+- **Working branch**: `major-version-reorg` (all migration PRs target this branch)
+- **Target dir**: `reference_versioned_docs/version-v4/`
+- **Do NOT touch**: `versioned_docs/` or `reference/`
+
+## Key Files
+
+- `v4-docs-implementation-plan.md` — Agent instructions (follow Part 1 closely)
+- `v4-docs-migration-map.md` — Authoritative source-to-target mapping per section
+- `v4-docs-reference-plan.md` — Structure philosophy and outline
+- `reference_versioned_sidebars/version-v4-sidebars.json` — Sidebar to update for each section
+- ~~`migration-context/link-placeholders/`~~ — **Deleted** (Part 3 link resolution complete)
+
+## Release Notes Location
+
+`release-notes/v4-tucker/4.X.0.md` (NOT `release_notes/`)
+
+## Completed Sections
+
+All Phase 1A–1D sections are complete and merged:
+
+- CLI, GraphQL Querying, Studio, Fastify Routes (Phase 1A)
+- Environment Variables, Static Files, HTTP, MQTT, Logging, Analytics (Phase 1B)
+- Security, Users & Roles, REST (PR #457), Database (PR #458), Resources (PR #459), Components (PR #460), Replication (PR #461) (Phase 1C)
+- Operations API (PR #462), Configuration (PR #463) (Phase 1D)
+
+## Key Decisions / Learnings
+
+- Each section gets its own branch `migration/[section-name]` off `major-version-reorg` (for phase 1 content generation)
+- PRs are draft by default, opened against `major-version-reorg`
+- `@relationship` in v4.7 source (not `@relation` from 4.3 release notes) — needs human verification
+- Audit log required for real-time messaging (MQTT/WebSocket) — verify still true
+- `schema.md` kept unified (overview + blobs + vectors); consider splitting if too long
+- System tables include: `hdb_raw_analytics`, `hdb_analytics`, `hdb_dataloader_hash`, `hdb_nodes`, `hdb_certificate`
+- Analytics detail lives in `analytics/overview.md`, not `database/system-tables.md`
+- Components section added `javascript-environment.md` (not in original plan)
+
+## Next Steps
+
+**Part 3 (Link Resolution) — Complete** on `link-resolution` branch (10 commits). Merge to `major-version-reorg` via PR review, then continue:
+
+**Part 4 (Cross-Reference Updates)** — Full plan in [`memory/part4-plan.md`](part4-plan.md).
+
+- Branch: `cross-reference-updates` off `major-version-reorg`
+- Scope: ~7 release note files + 1 learn guide with old `/docs/` links
+- **First step**: verify URL prefix for new reference pages (check `docusaurus.config.js`)
+
+**Part 5 (Redirects)** — Configure redirects from old paths (`/docs/reference/`, `/docs/developers/`, etc.) to new paths in `docusaurus.config.js`.
+
+### Part 3 Key Decisions
+
+- Operations table category links (e.g. `../operations-api/database.md`) → `../operations-api/operations.md` with section anchors (no sub-pages exist)
+- `resources/global-apis.md` never created → links redirected to `../components/javascript-environment.md`
+- SQL operations link → `../database/sql.md` (SQL moved from legacy per migration map)
+- `[Applications](TODO:applications/overview.md)` → `../components/overview.md`
+- Malformed `[TODO:path](TODO:path)` links in `components/overview.md` fixed with proper text
+
+Legacy section: single files only (no subfolders): `cloud.md`, `custom-functions.md`. SQL moved to `database/sql.md`.
+
+## Sidebar Pattern
+
+```json
+{
+	"type": "category",
+	"label": "Section Name",
+	"collapsible": false,
+	"className": "learn-category-header",
+	"items": [{ "type": "doc", "id": "section/page", "label": "Label" }]
+}
+```
+
+Insert new sections before the Legacy category at the bottom of the sidebar.

memory/part4-plan.md

@@ -0,0 +1,143 @@
+# Part 4: Cross-Reference Updates — Plan & Procedure
+
+## Overview
+
+Update links in `release-notes/` and `learn/` that point to old doc paths, mapping them to the new `reference_versioned_docs/version-v4/` structure.
+
+**Branch**: Create a new branch `cross-reference-updates` off `major-version-reorg` (after `link-resolution` is merged).
+
+**Commit strategy**: One commit per file group (release notes in one commit, learn guides in another, or broken down further if large).
+
+---
+
+## Scope of Changes
+
+### Release Notes (`release-notes/v4-tucker/`)
+
+171 files total. Only ~7 files have `/docs/` links that need updating. The full list of unique links found (grep: `(/docs/[^)"\ ]*)` across all `release-notes/v4-tucker/*.md`):
+
+| Old Path                                                                              | New Path                                                     | Notes                                               |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
+| `/docs/deployments/configuration`                                                     | `/docs/v4/configuration/overview`                            | 7 occurrences                                       |
+| `/docs/reference/resources`                                                           | `/docs/v4/resources/overview`                                | 4 occurrences                                       |
+| `/docs/developers/applications/defining-schemas`                                      | `/docs/v4/database/schema`                                   | 4 occurrences                                       |
+| `/docs/reference/graphql`                                                             | `/docs/v4/graphql-querying/overview`                         | 1 occurrence                                        |
+| `/docs/reference/components/extensions`                                               | `/docs/v4/components/extension-api`                          | 1 occurrence                                        |
+| `/docs/reference/components/applications?_highlight=github#adding-components-to-root` | `/docs/v4/components/applications#adding-components-to-root` | 1 occurrence                                        |
+| `/docs/reference/blob`                                                                | `/docs/v4/database/schema#blob-storage`                      | 1 occurrence                                        |
+| `/docs/developers/rest`                                                               | `/docs/v4/rest/overview`                                     | 1 occurrence                                        |
+| `/docs/developers/replication/sharding`                                               | `/docs/v4/replication/sharding`                              | 1 occurrence                                        |
+| `/docs/developers/replication/`                                                       | `/docs/v4/replication/overview`                              | 1 occurrence                                        |
+| `/docs/developers/real-time`                                                          | `/docs/v4/rest/websockets`                                   | 1 occurrence (real-time = websockets+SSE+MQTT)      |
+| `/docs/developers/operations-api/clustering`                                          | `/docs/v4/replication/clustering`                            | 1 occurrence                                        |
+| `/docs/developers/applications/data-loader`                                           | `/docs/v4/database/data-loader`                              | 1 occurrence                                        |
+| `/docs/deployments/harper-cli`                                                        | `/docs/v4/cli/overview`                                      | 1 occurrence                                        |
+| `/docs/administration/logging/`                                                       | `/docs/v4/logging/overview`                                  | 1 occurrence                                        |
+| `/docs/administration/cloning`                                                        | N/A — learn guide (not in reference)                         | Leave or link to learn guide if exists              |
+| `/docs/4.1/custom-functions/host-static`                                              | `/docs/v4/legacy/custom-functions`                           | Legacy redirect                                     |
+| `/docs/4.1/configuration#storage`                                                     | `/docs/v4/configuration/options#storage`                     | 1 occurrence                                        |
+| `/docs/4.1/configuration#session-affinity`                                            | `/docs/v4/configuration/options#http`                        | 1 occurrence (http section covers session affinity) |
+| `/docs/4.1/configuration#schemas`                                                     | `/docs/v4/database/schema`                                   | 1 occurrence                                        |
+
+> **NOTE**: The exact URL prefix for the new structure (`/docs/v4/`) needs to be verified. Check `docusaurus.config.js` or `reference_versioned_sidebars/version-v4-sidebars.json` for the versioned path prefix. It may be `/docs/v4/` or `/reference/v4/` or similar.
+
+**Files that contain links (to edit):**
+
+- `release-notes/v4-tucker/4.1.0.md` — `/docs/4.1/configuration#*` and `/docs/4.1/custom-functions/*`
+- `release-notes/v4-tucker/4.2.0.md` — `/docs/reference/resources`, `/docs/reference/components/*`
+- `release-notes/v4-tucker/4.3.0.md` — `/docs/reference/resources`
+- `release-notes/v4-tucker/4.4.0.md` — `/docs/developers/applications/defining-schemas`, `/docs/reference/resources`, `/docs/reference/graphql`
+- `release-notes/v4-tucker/4.5.0.md` — `/docs/reference/blob`, `/docs/deployments/configuration`
+
+**To find all affected files precisely**: `grep -rl "/docs/" release-notes/v4-tucker/`
+
+---
+
+### Learn Guides (`learn/`)
+
+Only 4 content files currently exist (most are stubs):
+
+- `learn/developers/harper-applications-in-depth.mdx`
+- `learn/getting-started/create-your-first-application.mdx`
+- `learn/getting-started/install-and-connect-harper.mdx`
+- `learn/index.mdx`
+
+Links found in `harper-applications-in-depth.mdx`:
+
+| Old Path                                         | New Path                                                     |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| `/docs/reference/components/built-in-extensions` | `/docs/v4/components/overview#built-in-extensions-reference` |
+| `/docs/reference/resources`                      | `/docs/v4/resources/overview`                                |
+| `/docs/reference/globals#logger`                 | `/docs/v4/logging/api`                                       |
+| `/docs/reference/resources/`                     | `/docs/v4/resources/overview`                                |
+| `/docs/reference/components/`                    | `/docs/v4/components/overview`                               |
+
+---
+
+## Procedure
+
+### Step 1: Verify URL prefix
+
+Before editing any links, confirm what the new URL prefix is for `reference_versioned_docs/version-v4/`. Check:
+
+```bash
+cat docusaurus.config.js | grep -A5 "reference_versioned"
+# or
+cat reference_versioned_sidebars/version-v4-sidebars.json | head -5
+```
+
+The prefix is likely `/docs/v4/` but confirm before proceeding.
+
+### Step 2: Find all affected release note files
+
+```bash
+grep -rl "/docs/" release-notes/v4-tucker/
+```
+
+This gives the exact list of files to edit.
+
+### Step 3: Edit release notes
+
+For each affected file, replace old `/docs/` paths with new `/docs/v4/` paths per the mapping table above.
+
+### Step 4: Edit learn guides
+
+Read each of the 4 learn guide files, apply the mapping table above.
+
+### Step 5: Check for any remaining old-path links across the whole repo
+
+```bash
+grep -rn "/docs/reference/" --include="*.md" --include="*.mdx" release-notes/ learn/
+grep -rn "/docs/developers/" --include="*.md" --include="*.mdx" release-notes/ learn/
+grep -rn "/docs/deployments/" --include="*.md" --include="*.mdx" release-notes/ learn/
+grep -rn "/docs/administration/" --include="*.md" --include="*.mdx" release-notes/ learn/
+grep -rn "/docs/4\." --include="*.md" --include="*.mdx" release-notes/ learn/
+```
+
+### Step 6: Commit
+
+- Commit release notes changes: `docs(cross-refs): update old /docs/ links in release notes to v4 reference paths`
+- Commit learn guide changes: `docs(cross-refs): update old /docs/ links in learn guides to v4 reference paths`
+
+---
+
+## Key Uncertainties to Resolve
+
+1. **URL prefix** — Confirm whether new reference pages are served at `/docs/v4/`, `/reference/v4/`, or another prefix. **Critical before editing any links.**
+2. **`/docs/administration/cloning`** — This was flagged in migration map as "move to Learn guide." If no learn guide exists yet, either leave as-is (broken link) or remove the link text.
+3. **`/docs/developers/real-time`** — This page covered WebSockets, SSE, and MQTT. Best split into: WebSockets content → `rest/websockets`, MQTT content → `mqtt/overview`. In context of release notes, pick whichever is most relevant to the surrounding text.
+
+---
+
+## Non-Goals for Part 4
+
+- Do NOT edit `versioned_docs/` files
+- Do NOT edit `reference_versioned_docs/` files (those were handled in Part 3)
+- Do NOT update links in the v1/v2/v3 release notes (out of scope)
+- Do NOT update links in other config files (docusaurus.config.js, sidebars, etc.) — that's Part 5
+
+---
+
+## After Part 4
+
+Proceed to **Part 5: Redirects** — configure redirects from old `/docs/developers/`, `/docs/reference/`, etc. paths to the new `/docs/v4/` equivalents in `docusaurus.config.js` (or wherever redirects are configured).