From 44fc4dcfcd5e61302011fb581ebbb538dd1cc394 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Mon, 8 Jun 2026 22:17:46 -0600 Subject: [PATCH 1/2] docs: add Learn section outline plan (#519) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add plans/learn-section-outline/ — an agentic-first plan for building out the Learn track: - Reconciles the original Confluence outline against current learn/ content (3 guides already shipped: using-agents, harper-applications-in-depth, and the full caching series) and flags the inverted Custom Resources dependency. - Maps legacy /docs/ paths to current /reference/ sources, with the legacy tree recoverable at git ref 0f754c5f. - Phase 1: create-issues.sh generates 20 [Learn] tracking issues (label `content`, type `Feature`) from per-guide body files in issues/. - Phase 2: a per-guide generation workflow — worktree/branch, draft from the guide template + reference sources, local /review pass, build check, one PR per guide with @HarperFast/developers requested as reviewer. Closes #519 Co-Authored-By: Claude Opus 4.8 (1M context) --- plans/learn-section-outline/README.md | 218 ++++++++++++++++++ plans/learn-section-outline/create-issues.sh | 63 +++++ .../issues/01-deploy-to-fabric.md | 16 ++ .../issues/04-defining-databases-tables.md | 17 ++ .../issues/05-loading-data.md | 14 ++ .../issues/06-users-and-roles.md | 13 ++ .../issues/07-querying-interacting.md | 14 ++ .../issues/08-real-time-intro.md | 11 + .../issues/09-custom-resources.md | 12 + .../issues/10-web-apps.md | 14 ++ .../issues/12-data-with-replication.md | 11 + .../issues/13-plugin-development.md | 12 + .../issues/14-running-locally.md | 12 + .../issues/15-running-in-container.md | 10 + .../issues/16-fabric-deployment.md | 12 + .../issues/17-manual-replication-setup.md | 11 + .../issues/18-logging.md | 11 + .../issues/19-analytics-grafana.md | 9 + .../issues/20-certificates.md | 13 ++ .../issues/21-security-configuration.md | 8 + .../issues/22-compaction.md | 8 + plans/learn-section-outline/issues/23-jobs.md | 8 + 22 files changed, 517 insertions(+) create mode 100644 plans/learn-section-outline/README.md create mode 100755 plans/learn-section-outline/create-issues.sh create mode 100644 plans/learn-section-outline/issues/01-deploy-to-fabric.md create mode 100644 plans/learn-section-outline/issues/04-defining-databases-tables.md create mode 100644 plans/learn-section-outline/issues/05-loading-data.md create mode 100644 plans/learn-section-outline/issues/06-users-and-roles.md create mode 100644 plans/learn-section-outline/issues/07-querying-interacting.md create mode 100644 plans/learn-section-outline/issues/08-real-time-intro.md create mode 100644 plans/learn-section-outline/issues/09-custom-resources.md create mode 100644 plans/learn-section-outline/issues/10-web-apps.md create mode 100644 plans/learn-section-outline/issues/12-data-with-replication.md create mode 100644 plans/learn-section-outline/issues/13-plugin-development.md create mode 100644 plans/learn-section-outline/issues/14-running-locally.md create mode 100644 plans/learn-section-outline/issues/15-running-in-container.md create mode 100644 plans/learn-section-outline/issues/16-fabric-deployment.md create mode 100644 plans/learn-section-outline/issues/17-manual-replication-setup.md create mode 100644 plans/learn-section-outline/issues/18-logging.md create mode 100644 plans/learn-section-outline/issues/19-analytics-grafana.md create mode 100644 plans/learn-section-outline/issues/20-certificates.md create mode 100644 plans/learn-section-outline/issues/21-security-configuration.md create mode 100644 plans/learn-section-outline/issues/22-compaction.md create mode 100644 plans/learn-section-outline/issues/23-jobs.md diff --git a/plans/learn-section-outline/README.md b/plans/learn-section-outline/README.md new file mode 100644 index 00000000..894dbc6c --- /dev/null +++ b/plans/learn-section-outline/README.md @@ -0,0 +1,218 @@ +# Learn Section Outline + +Plan for building out the **Learn** guided-learning track. Tracks +[#519](https://github.com/HarperFast/documentation/issues/519). + +This plan is **agentic-first**: it is written so an AI agent (or a contributor +driving one) can execute it end-to-end — generating tracking issues, then +authoring each guide in its own branch with a local review pass and an individual +PR. Humans review the PRs. + +--- + +## 1. Background + +The Learn track was bootstrapped from a Confluence content outline. The original +outline referenced a `/docs/...` structure that **no longer exists** — the docs +were restructured into `learn/`, `reference/`, and `fabric/` in commit `01c78b8e` +("initializing the new learn tab", #404). + +Two things this plan corrects from the original outline: + +1. **Paths moved `/docs/` → `/reference/`** (and the legacy tree is recoverable — + see §3). +2. **Several planned guides already shipped** — they must be skipped (see §2). + +## 2. Current state of `learn/` + +``` +learn/ + index.mdx + _guide-template.mdx ← author template (follow this) + getting-started/ + install-and-connect-harper.mdx ✅ shipped + create-your-first-application.mdx ✅ shipped + using-agents.mdx ✅ shipped (was "AI Best Practices") + developers/ + harper-applications-in-depth.mdx ✅ shipped (was "Key Harper Application Features") + caching-with-harper.mdx ✅ shipped (was "Caching Pt. 1") + active-caching-subscriptions.mdx ✅ shipped (caching series) + semantic-caching-vector-indexing.mdx ✅ shipped (caching series) + write-through-caching.mdx ✅ shipped (caching series) + caching-ai-generations.mdx ✅ shipped (caching series) + administration/ + coming-soon.md placeholder +``` + +**The entire caching series shipped ahead of plan.** But **Custom Resources** — +declared a *prerequisite* for caching in the original outline — does **not** exist +yet. The dependency is currently inverted; Custom Resources (guide #9 below) should +be prioritized and the shipped caching guides back-linked to it once it lands. + +## 3. Path resolution: `/docs/` → `/reference/` + +For each planned guide, prefer the **current `reference/` doc** as the source of +truth. The deleted legacy `/docs/` page is available for narrative/tutorial framing +that may not have survived the reference rewrite. + +> **Legacy content** lives at git ref **`0f754c5f`** (parent of `01c78b8e`): +> ```bash +> git show 0f754c5f:docs/ +> git ls-tree -r --name-only 0f754c5f | grep '^docs/' +> ``` + +| Topic | Legacy `/docs/` path | Current `reference/` source | +|---|---|---| +| Architecture / core concepts | `foundations/harper-architecture`, `foundations/core-concepts` | `components/overview.md`, `index.md` | +| Applications | `developers/applications/index` | `components/applications.md` | +| Debugging | `developers/applications/debugging` | `configuration/debugging.md` | +| Schema | `developers/applications/defining-schemas` | `database/schema.md` | +| Data Loader | `developers/applications/data-loader` | `database/data-loader.md` | +| Roles | `developers/applications/defining-roles` | `users-and-roles/configuration.md` | +| Users & roles | `developers/security/users-and-roles` | `users-and-roles/overview.md` | +| Custom resources | `developers/applications/index` | `resources/resource-api.md`, `resources/overview.md` | +| Query optimization | `reference/resources/query-optimization` | `resources/query-optimization.md` | +| REST | `developers/rest` | `rest/overview.md`, `rest/querying.md` | +| Real-time | `developers/real-time` | `rest/websockets.md`, `rest/server-sent-events.md` | +| Web apps / routes | `developers/applications/web-applications`, `.../define-routes` | `static-files/overview.md`, `components/nextjs.md`, `fastify-routes/overview.md` | +| Plugins / extensions | `reference/components/plugins`, `.../extensions` | `components/plugin-api.md`, `components/extension-api.md` | +| Replication / sharding | `developers/replication/sharding`, `.../index` | `replication/sharding.md`, `replication/overview.md`, `replication/clustering.md` | +| Logging | `administration/logging/*` | `logging/overview.md`, `logging/configuration.md`, `logging/api.md`, `logging/operations.md` | +| Analytics | `developers/operations-api/analytics` | `analytics/overview.md`, `analytics/operations.md` | +| Certificates | `developers/security/certificate-management`, `.../certificate-verification` | `security/certificate-management.md`, `security/certificate-verification.md` | +| Security config | `developers/security/configuration` | `security/configuration.md`, `http/configuration.md`, `http/tls.md` | +| Compaction | `administration/compact` _(named `compact`)_ | `database/compaction.md` | +| Jobs | `administration/jobs` | `database/jobs.md`, `operations-api/operations.md` | + +> **In-guide links** should use the published doc URL form `/reference/v5/...` +> (the current docs version), not raw repo paths. Repo paths above are for the +> author/agent to read source material. + +## 4. Guide inventory & ordering + +20 guides to produce (3 already shipped are omitted). The order encodes the +intended authoring sequence; the Developers track is a dependency chain. + +**Getting Started** +1. Deploy to Fabric + +**Developers** (author roughly in order — each builds on the previous) +4. Defining Databases and Tables +5. Loading Data +6. Users & Roles +7. Querying and Interacting with Data +8. Real-Time Data Access Introduction +9. **Custom Resources** — _prioritize; prerequisite for the already-shipped caching guides_ +10. Web Apps +12. Data with Replication +13. Plugin Development + +**Administration** +14. Running Harper Locally · 15. Running Harper in a Container · 16. Fabric +Deployment Guide · 17. Manual / Local Replication Setup · 18. Logging · +19. Analytics & Grafana Plugin · 20. Certificate Management & Verification · +21. Security Configuration · 22. Compaction · 23. Jobs + +_(Numbers 2, 3, 11 intentionally absent — already shipped.)_ + +Full per-guide scope is in [`issues/`](./issues) — one Markdown file per guide, +used verbatim as the GitHub issue body in Phase 1. + +### Overlaps with existing open issues +Dedupe before/at issue creation — cross-link, and close pure duplicates: +- #16 Fabric Deployment ↔ **#502** (CI/CD Fabric deploy) — strongest overlap; merge. +- #1 Deploy to Fabric ↔ #478, #502. +- #5 Loading Data / #13 Plugin Dev ↔ **#513** (restart behavior). +- #12 / #17 / #20 ↔ #510, #511 (clustering & TLS). +- #7 Querying ↔ #490 (relational selects). + +## 5. Conventions + +- **Template:** every guide follows `learn/_guide-template.mdx` — intro, + *What You Will Learn*, *Prerequisites*, body sections, *Additional Resources*. +- **Location:** `learn/
/.mdx` (`getting-started` | `developers` | + `administration`). +- **Sidebar:** register the new doc in `sidebarsLearn.ts`. Getting Started and + Developers use explicit ordered entries; Administration is `autogenerated` — + adding a file there is enough, but set front-matter `sidebar_position` for order. + Remove `administration/coming-soon.md` once the first admin guide lands. +- **Issues:** label `content`, issue **type `Feature`**, title prefix `[Learn]`. +- **PRs:** one PR per guide. Title `docs: add Learn guide — `. Link the PR to + its issue with `Closes #`. Request review from **`@HarperFast/developers`** + (per `.github/CODEOWNERS`). +- **Branches/commits:** use a worktree per guide (see §7). Commit messages follow + the repo's `docs: ...` convention. + +## 6. Phase 1 — generate tracking issues + +[`create-issues.sh`](./create-issues.sh) creates the 20 `[Learn]` issues from the +body files in [`issues/`](./issues), each labeled `content` and typed `Feature`. + +```bash +cd plans/learn-section-outline +./create-issues.sh # dry-run — preview +./create-issues.sh --create # create the issues +``` + +It skips the shipped guides and applies the `Feature` type via the REST API (since +`gh` has no `--type` flag). Record the resulting issue numbers — Phase 2 references +them. + +## 7. Phase 2 — agentic guide generation + +For **each** guide issue, an agent runs this loop. One guide → one branch → one PR. +Do them one or a few at a time; respect the §4 ordering (Custom Resources early). + +1. **Isolate.** Create a worktree + branch off latest `main`: + ```bash + git worktree add "$PWD/.claude/worktrees/learn-" -b learn/ + ``` +2. **Gather source.** Read the linked issue body, the `reference/` sources it + names (§3), the shipped guides it builds on, and `learn/_guide-template.mdx`. + Pull legacy narrative with `git show 0f754c5f:docs/...` where useful. +3. **Draft.** Write `learn/
/.mdx` against the template. Use real, + runnable examples (`curl`/`fetch`, Operations API, CLI). Link related guides and + `/reference/v5/...` docs. Register it in `sidebarsLearn.ts`. +4. **Self-review (local, agentic).** Run the internal review skill on the diff + before opening the PR: + ``` + /review + ``` + Use `/code-review` for prose/example correctness and `/deep-review` when a guide + ships runnable code/config worth a reliability pass. Address findings, repeat + until clean. +5. **Verify the build.** `node scripts/prebuild.js && docusaurus build` (or + `docusaurus start`) — confirm the page renders, sidebar entry appears, and links + resolve. See `CONTRIBUTING.md` for the `serve-handler` patch caveat. +6. **Commit & push.** + ```bash + git add learn/
/.mdx sidebarsLearn.ts + git commit -m "docs: add Learn guide — " + git push -u origin learn/ + ``` +7. **Open the PR.** `Closes #`; request review from + `@HarperFast/developers`: + ```bash + gh pr create --base main --head learn/ \ + --title "docs: add Learn guide — " \ + --body "Closes #. ..." \ + --reviewer HarperFast/developers + ``` +8. **Iterate** on review feedback. On merge, clean up: + `git worktree remove "$PWD/.claude/worktrees/learn-"`. + +### Guardrails for the agent +- One guide per PR — keep diffs reviewable. +- Never invent APIs/behavior: every claim traces to a `reference/` doc or verified + example. When unsure, flag it in the PR description rather than guessing. +- Match the voice and depth of the already-shipped guides + (`learn/developers/caching-with-harper.mdx` is a good exemplar). +- Honor prerequisites: a guide may assume only Getting Started + guides earlier in + the §4 order. + +## 8. Open decisions (for maintainers) +- Whether to close/merge #502 into guide #16. +- Whether to add a dedicated `learn` label for track-wide filtering (currently + `content` only). +- v4 vs v5 scope for guides #12/#14/#17 (replication/install) given `reference/` is + versioned. diff --git a/plans/learn-section-outline/create-issues.sh b/plans/learn-section-outline/create-issues.sh new file mode 100755 index 00000000..82fd3296 --- /dev/null +++ b/plans/learn-section-outline/create-issues.sh @@ -0,0 +1,63 @@ +#!/usr/bin/env bash +# Phase 1 — create the outstanding [Learn] tracking issues from the body files in +# ./issues/. Each issue is labeled `content` and typed `Feature`. +# +# ./create-issues.sh # dry-run (lists what would be created) +# ./create-issues.sh --create # actually create issues +# +# Skips guides #2 (using-agents), #3 (harper-applications-in-depth) and the #11 +# caching series — those are already shipped in learn/. +# +# `gh` (<= 2.92) has no `--type` flag, so the issue type is applied via the REST +# API immediately after creation. Org issue type "Feature" must exist. + +set -euo pipefail + +REPO="HarperFast/documentation" +LABELS="content" +ISSUE_TYPE="Feature" +DIR="$(cd "$(dirname "$0")" && pwd)/issues" +create=false +[[ "${1:-}" == "--create" ]] && create=true + +# Manifest: "title|body-file" (order encodes the intended authoring sequence). +ISSUES=( + "[Learn] Deploy to Fabric|01-deploy-to-fabric.md" + "[Learn] Defining Databases and Tables|04-defining-databases-tables.md" + "[Learn] Loading Data|05-loading-data.md" + "[Learn] Users & Roles|06-users-and-roles.md" + "[Learn] Querying and Interacting with Data|07-querying-interacting.md" + "[Learn] Real-Time Data Access Introduction|08-real-time-intro.md" + "[Learn] Custom Resources|09-custom-resources.md" + "[Learn] Web Apps|10-web-apps.md" + "[Learn] Data with Replication|12-data-with-replication.md" + "[Learn] Plugin Development|13-plugin-development.md" + "[Learn] Running Harper Locally|14-running-locally.md" + "[Learn] Running Harper in a Container|15-running-in-container.md" + "[Learn] Fabric Deployment Guide|16-fabric-deployment.md" + "[Learn] Manual / Local Replication Setup|17-manual-replication-setup.md" + "[Learn] Logging|18-logging.md" + "[Learn] Analytics & Grafana Plugin|19-analytics-grafana.md" + "[Learn] Certificate Management & Verification|20-certificates.md" + "[Learn] Security Configuration|21-security-configuration.md" + "[Learn] Compaction|22-compaction.md" + "[Learn] Jobs|23-jobs.md" +) + +for entry in "${ISSUES[@]}"; do + title="${entry%%|*}" + file="$DIR/${entry##*|}" + [[ -f "$file" ]] || { echo "missing body: $file" >&2; exit 1; } + if $create; then + url=$(gh issue create --repo "$REPO" --title "$title" --label "$LABELS" --body-file "$file") + num="${url##*/}" + gh api --method PATCH "repos/$REPO/issues/$num" -f "type=$ISSUE_TYPE" >/dev/null + echo "created: $title (type=$ISSUE_TYPE) -> $url" + else + echo "would create: $title (label: $LABELS, type: $ISSUE_TYPE, body: issues/${entry##*|})" + fi +done + +echo +echo "Total: ${#ISSUES[@]} issues." +$create && echo "Done." || echo "DRY RUN — re-run with --create to create these issues." diff --git a/plans/learn-section-outline/issues/01-deploy-to-fabric.md b/plans/learn-section-outline/issues/01-deploy-to-fabric.md new file mode 100644 index 00000000..2281a7ac --- /dev/null +++ b/plans/learn-section-outline/issues/01-deploy-to-fabric.md @@ -0,0 +1,16 @@ +**Section:** Getting Started — third entry, after *Install and Connect Harper* and *Create Your First Application*. + +Bridges local development and cloud deployment for first-time Harper developers. + +## Goals / Scope +- Expand on quickstart concepts — define "Application" and "Plugin" as first encountered (do not defer to a Core Concepts page). +- Add detail when introducing each new concept for the first time. +- Follow `learn/_guide-template.mdx`: structured *What You Will Learn*, *Prerequisites*, *Additional Resources*. + +## Reference source material +- Architecture & concepts: `reference/components/overview.md`, `reference/index.md` +- Legacy narrative (optional): `git show 0f754c5f:docs/foundations/harper-architecture.md`, `git show 0f754c5f:docs/foundations/core-concepts.md` + +## Notes +- First-time developer guide — keep conceptual overhead low. +- Related existing issues: #502 (CI/CD deploy guide for Fabric), #478 (Harper deploy behavior). This is the onboarding-level deploy; the *Fabric Deployment Guide* (Administration) is the deeper version. diff --git a/plans/learn-section-outline/issues/04-defining-databases-tables.md b/plans/learn-section-outline/issues/04-defining-databases-tables.md new file mode 100644 index 00000000..7dae575b --- /dev/null +++ b/plans/learn-section-outline/issues/04-defining-databases-tables.md @@ -0,0 +1,17 @@ +**Section:** Developers. Evolves the schema system from Getting Started toward interactive examples and broader database/table configuration. + +## Goals / Scope +- Build from the schema reference: `reference/database/schema.md`. +- Interactive examples: show what custom directives do via `curl`/`fetch`. +- Show Operations API usage (e.g. `create_table`) and CLI equivalents — `reference/operations-api/operations.md`, `reference/cli/commands.md`. +- Mention caching briefly, link to the shipped caching guides (`learn/developers/caching-with-harper.mdx`). +- Keep using the basic REST APIs from Getting Started for data interaction. +- Brief bonus section on replication; note v5 OSS does not enable replication by default. +- Keep scope lean — complex interaction comes later. + +## Reference source material +- `reference/database/schema.md`, `reference/database/overview.md` +- Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/defining-schemas.md` + +## Notes +- Dependency chain: first Developers-track guide → *Loading Data* → *Users & Roles* → *Querying* → *Real-Time* → *Custom Resources* → *Web Apps*. diff --git a/plans/learn-section-outline/issues/05-loading-data.md b/plans/learn-section-outline/issues/05-loading-data.md new file mode 100644 index 00000000..38a34641 --- /dev/null +++ b/plans/learn-section-outline/issues/05-loading-data.md @@ -0,0 +1,14 @@ +**Section:** Developers. Builds on the tables from *Defining Databases and Tables*; demonstrates bulk loading via the Data Loader plugin and other mechanisms. + +## Goals / Scope +- Multiple ways to load data, kept approachable (no deep auth/roles yet — that is the next guide). +- Use Data Loader to explain the Harper application lifecycle: it survives restarts → frame Harper as a long-running system and how to think about lifecycle in dev vs production. +- Full end-to-end: load data → query with basic REST / Operations / CLI. +- Audience is ~4 guides in: comfortable with key concepts, not experts. + +## Reference source material +- `reference/database/data-loader.md` +- Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/data-loader.md` + +## Notes +- Related existing issue #513 (Document Harper restart behavior and guarantees) covers the lifecycle/restart framing — cross-link or fold in. diff --git a/plans/learn-section-outline/issues/06-users-and-roles.md b/plans/learn-section-outline/issues/06-users-and-roles.md new file mode 100644 index 00000000..86f02be3 --- /dev/null +++ b/plans/learn-section-outline/issues/06-users-and-roles.md @@ -0,0 +1,13 @@ +**Section:** Developers. Comprehensive guide to Harper's built-in User and Role system, scoping what it is and is not for. + +## Goals / Scope +- Iterate on the users-and-roles reference: `reference/users-and-roles/overview.md`, `reference/users-and-roles/configuration.md`, `reference/users-and-roles/operations.md`. +- Explain how roles matter specifically to application developers. +- Define clearly: native Users & Roles is for **database permissions**, not for building custom user/auth systems. +- Framing: "if you are content with users/roles being an internally defined, structured thing, great — for more control over your user/role schema, build your own." +- Show enforcement across REST, Operations API, CLI — expected successes and errors. +- Link to security and authentication guides. + +## Reference source material +- `reference/users-and-roles/*` +- Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/defining-roles.md`, `git show 0f754c5f:docs/developers/security/users-and-roles.md` diff --git a/plans/learn-section-outline/issues/07-querying-interacting.md b/plans/learn-section-outline/issues/07-querying-interacting.md new file mode 100644 index 00000000..7b52f143 --- /dev/null +++ b/plans/learn-section-outline/issues/07-querying-interacting.md @@ -0,0 +1,14 @@ +**Section:** Developers. Advanced querying, building on REST + Resource API basics. + +## Goals / Scope +- Advanced scenarios: relational tables, computed properties, HNSW indexing. +- Query optimization (intro-level; deeper guide possible later). +- Relational data examples if not covered earlier. +- Querying for computed properties and other complex DB scenarios. + +## Reference source material +- `reference/resources/query-optimization.md`, `reference/rest/querying.md`, `reference/rest/overview.md` +- Legacy narrative (optional): `git show 0f754c5f:docs/developers/rest.md` + +## Notes +- Related existing issue #490 (relational selects and conditions in `search_by_conditions`). Cross-link. diff --git a/plans/learn-section-outline/issues/08-real-time-intro.md b/plans/learn-section-outline/issues/08-real-time-intro.md new file mode 100644 index 00000000..a5f2e823 --- /dev/null +++ b/plans/learn-section-outline/issues/08-real-time-intro.md @@ -0,0 +1,11 @@ +**Section:** Developers. Introduces real-time data access patterns, including WebSockets, with both basic tables and custom resources. + +## Goals / Scope +- Demonstrate WebSockets and other real-time mechanisms. +- Show usage with both basic tables and custom resources. +- Consider GIFs / video embeds to illustrate live interactivity. +- Keep scope simple — complex scenarios (e.g. live chat) come after Custom Resources and the (shipped) Caching guides. + +## Reference source material +- `reference/rest/websockets.md`, `reference/rest/server-sent-events.md`, `reference/mqtt/overview.md` +- Legacy narrative (optional): `git show 0f754c5f:docs/developers/real-time.md` diff --git a/plans/learn-section-outline/issues/09-custom-resources.md b/plans/learn-section-outline/issues/09-custom-resources.md new file mode 100644 index 00000000..c4034364 --- /dev/null +++ b/plans/learn-section-outline/issues/09-custom-resources.md @@ -0,0 +1,12 @@ +**Section:** Developers. Deep-dive on one of Harper's most important features. + +## Goals / Scope +- Build on Getting Started + the Resource API reference: `reference/resources/resource-api.md`, `reference/resources/overview.md`, `reference/components/applications.md`. +- Show how requests of all forms (REST, Operations, CLI, WebSocket) work with custom resources. +- **Resource API v2 only.** +- Cover the Resource API from both consumer and provider perspectives. +- Mention caching but link to the shipped caching guides rather than covering it here. +- Example can be simple but must demonstrate the full feature surface. + +## Notes +- **Priority: elevate this.** The already-shipped caching guides (`learn/developers/caching-*.mdx`) treat Custom Resources as a prerequisite that does not exist yet. This back-fills the gap — add a back-link from the caching guides once this lands. diff --git a/plans/learn-section-outline/issues/10-web-apps.md b/plans/learn-section-outline/issues/10-web-apps.md new file mode 100644 index 00000000..17ad3346 --- /dev/null +++ b/plans/learn-section-outline/issues/10-web-apps.md @@ -0,0 +1,14 @@ +**Section:** Developers. From simple static hosting to more complex server-side setups. + +## Goals / Scope +- **Part 1 — Static hosting:** static plugin as the starting point for client-side apps; working React + Vite example; link to a collection of static framework templates. +- **Part 2 — Complex web apps:** introduce plugin-development concepts (without a full plugin guide yet); show existing web app plugins; demonstrate getting started with Next.js or similar using existing plugins. +- Discuss server-side code (direct Harper resource access) vs client-side (networking interfaces only). +- Dev server and deployment basics; link to the Administration guide for depth. + +## Reference source material +- `reference/static-files/overview.md`, `reference/components/nextjs.md`, `reference/fastify-routes/overview.md` +- Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/web-applications.md` + +## Notes +- The `@harperfast/nextjs` plugin docs were recently updated (#505) — reference them. diff --git a/plans/learn-section-outline/issues/12-data-with-replication.md b/plans/learn-section-outline/issues/12-data-with-replication.md new file mode 100644 index 00000000..f24ac3cd --- /dev/null +++ b/plans/learn-section-outline/issues/12-data-with-replication.md @@ -0,0 +1,11 @@ +**Section:** Developers. Goes deeper on replication, building on the brief intro from *Defining Databases and Tables*. + +## Goals / Scope +- Expand on the replication reference: `reference/replication/sharding.md`, `reference/replication/overview.md`, `reference/replication/clustering.md`. +- Cover more complex replication scenarios. +- Link to the Administration-side *Manual / Local Replication Setup* guide. +- Include utility scripts for local setup. +- Notes on replication availability/limitations in v5. + +## Notes +- Related existing issues: #510 (clustering troubleshooting), #511 (clustering TLS best practices). Cross-link. diff --git a/plans/learn-section-outline/issues/13-plugin-development.md b/plans/learn-section-outline/issues/13-plugin-development.md new file mode 100644 index 00000000..9d2833c5 --- /dev/null +++ b/plans/learn-section-outline/issues/13-plugin-development.md @@ -0,0 +1,12 @@ +**Section:** Developers. Standalone guide for developing custom Harper plugins using the new plugin API. + +## Goals / Scope +- Walk through the new plugin API in detail. +- Go deep on plugin and application lifecycle. +- Demonstrate the restart request process. + +## Reference source material +- `reference/components/plugin-api.md`, `reference/components/extension-api.md`, `reference/components/overview.md` + +## Notes +- Related existing issue #513 (restart behavior/guarantees) — the restart-request process overlaps; cross-link. diff --git a/plans/learn-section-outline/issues/14-running-locally.md b/plans/learn-section-outline/issues/14-running-locally.md new file mode 100644 index 00000000..c059a70c --- /dev/null +++ b/plans/learn-section-outline/issues/14-running-locally.md @@ -0,0 +1,12 @@ +**Section:** Administration. Running Harper locally for development. + +## Goals / Scope +- v5: split between "standard installation" and "from source". +- v4: installation only. +- Multiple install configurations. +- Useful setup/teardown scripts. +- Configuration tips and defaults for dev vs production. + +## Reference source material +- `reference/cli/overview.md`, `reference/configuration/overview.md`, `reference/configuration/options.md` +- Existing guide to build on: `learn/getting-started/install-and-connect-harper.mdx` diff --git a/plans/learn-section-outline/issues/15-running-in-container.md b/plans/learn-section-outline/issues/15-running-in-container.md new file mode 100644 index 00000000..7576845b --- /dev/null +++ b/plans/learn-section-outline/issues/15-running-in-container.md @@ -0,0 +1,10 @@ +**Section:** Administration. Like *Running Harper Locally* but scoped to containers. + +## Goals / Scope +- Container-specific considerations: port forwarding, environment variables, mounted dev dir, etc. + +## Reference source material +- `reference/environment-variables/overview.md`, `reference/configuration/options.md` + +## Notes +- Reference the v5 Docker image name change (#476, closed) so the image name is correct. diff --git a/plans/learn-section-outline/issues/16-fabric-deployment.md b/plans/learn-section-outline/issues/16-fabric-deployment.md new file mode 100644 index 00000000..a8a0c7f0 --- /dev/null +++ b/plans/learn-section-outline/issues/16-fabric-deployment.md @@ -0,0 +1,12 @@ +**Section:** Administration. Deploying and working with Harper on Fabric, developer-focused. + +## Goals / Scope +- Pull from existing Fabric docs (`fabric/`) and adapt to the Learn guide format. +- Developer-focused: what is possible with a Fabric instance (e.g. deploying from CLI). +- UI-based Fabric docs stay in the Fabric section; this guide is CLI/developer-facing. + +## Reference source material +- `fabric/` (existing Fabric section), `reference/cli/commands.md` + +## Notes +- **Strong overlap with existing issue #502** ("Add a CI/CD deploy guide for Harper Fabric") — recommend merging/closing #502 into this, or scoping #502 as the CI/CD half. Also relates to #478 and the Getting Started *Deploy to Fabric* guide. diff --git a/plans/learn-section-outline/issues/17-manual-replication-setup.md b/plans/learn-section-outline/issues/17-manual-replication-setup.md new file mode 100644 index 00000000..62e36ae9 --- /dev/null +++ b/plans/learn-section-outline/issues/17-manual-replication-setup.md @@ -0,0 +1,11 @@ +**Section:** Administration. Admin-side guide for setting up replication manually/locally. Complements the developer-side *Data with Replication* guide. + +## Goals / Scope +- Feature support details specific to v5. +- Helpful utility scripts for local setup. + +## Reference source material +- `reference/replication/overview.md`, `reference/replication/clustering.md` + +## Notes +- Related existing issues: #510 (clustering troubleshooting), #511 (clustering TLS). Cross-link. diff --git a/plans/learn-section-outline/issues/18-logging.md b/plans/learn-section-outline/issues/18-logging.md new file mode 100644 index 00000000..9618921c --- /dev/null +++ b/plans/learn-section-outline/issues/18-logging.md @@ -0,0 +1,11 @@ +**Section:** Administration. Turns existing Logging reference content into a practical usage guide. + +## Goals / Scope +- Iterate on the logging reference: `reference/logging/overview.md`, `reference/logging/configuration.md`, `reference/logging/api.md`, `reference/logging/operations.md`. +- Start simple (basic config/usage), progress to advanced (log rotation, etc.). +- Possibly third-party log consumers (DataDog, etc.) — may warrant follow-on guides. +- Ensure structured reference docs for logging APIs/config exist or are linked. + +## Reference source material +- `reference/logging/*` +- Legacy narrative (optional): `git show 0f754c5f:docs/administration/logging/index.md` diff --git a/plans/learn-section-outline/issues/19-analytics-grafana.md b/plans/learn-section-outline/issues/19-analytics-grafana.md new file mode 100644 index 00000000..6d68d08e --- /dev/null +++ b/plans/learn-section-outline/issues/19-analytics-grafana.md @@ -0,0 +1,9 @@ +**Section:** Administration. Understanding and using Harper's analytics features, with Grafana as the primary demo. + +## Goals / Scope +- Deep dive on Harper analytics features. +- Grafana as the key demonstration. +- Other third-party integrations could live in separate guides. + +## Reference source material +- `reference/analytics/overview.md`, `reference/analytics/operations.md` diff --git a/plans/learn-section-outline/issues/20-certificates.md b/plans/learn-section-outline/issues/20-certificates.md new file mode 100644 index 00000000..cc1e29b7 --- /dev/null +++ b/plans/learn-section-outline/issues/20-certificates.md @@ -0,0 +1,13 @@ +**Section:** Administration. Practical usage guide for certificate management and verification, evolving reference content into an interactive guide. + +## Goals / Scope +- Iterate on the security reference: `reference/security/certificate-management.md`, `reference/security/certificate-verification.md`. +- Walk through actual setup steps, not just reference. +- Demonstrate how certificates affect requests via `fetch`/`curl`. +- Consider splitting into two guides depending on complexity. + +## Reference source material +- `reference/security/certificate-management.md`, `reference/security/certificate-verification.md`, `reference/http/tls.md` + +## Notes +- Related existing issue #511 (clustering TLS certificate best practices). Cross-link. diff --git a/plans/learn-section-outline/issues/21-security-configuration.md b/plans/learn-section-outline/issues/21-security-configuration.md new file mode 100644 index 00000000..6875a1f9 --- /dev/null +++ b/plans/learn-section-outline/issues/21-security-configuration.md @@ -0,0 +1,8 @@ +**Section:** Administration. Configuring Harper's security features (CORS, SSL) and how settings affect runtime behavior. + +## Goals / Scope +- Walk through CORS and SSL config with concrete before/after request examples. +- Use real `curl`/`fetch` examples to show the impact of each setting. + +## Reference source material +- `reference/security/configuration.md`, `reference/security/overview.md`, `reference/http/configuration.md`, `reference/http/tls.md` diff --git a/plans/learn-section-outline/issues/22-compaction.md b/plans/learn-section-outline/issues/22-compaction.md new file mode 100644 index 00000000..4da60423 --- /dev/null +++ b/plans/learn-section-outline/issues/22-compaction.md @@ -0,0 +1,8 @@ +**Section:** Administration. Practical guide to Compaction, expanding reference content with a full working example. + +## Goals / Scope +- Iterate on the compaction reference: `reference/database/compaction.md`. +- Full end-to-end example with requests; do not re-explain schemas/data loading (link to those guides) but use them for context. + +## Reference source material +- `reference/database/compaction.md` diff --git a/plans/learn-section-outline/issues/23-jobs.md b/plans/learn-section-outline/issues/23-jobs.md new file mode 100644 index 00000000..9a1844a5 --- /dev/null +++ b/plans/learn-section-outline/issues/23-jobs.md @@ -0,0 +1,8 @@ +**Section:** Administration. Practical guide to Harper Jobs with full, interactive examples. + +## Goals / Scope +- Iterate on the jobs reference: `reference/database/jobs.md`. +- Demonstrate job operations end-to-end with complete working examples. + +## Reference source material +- `reference/database/jobs.md`, `reference/operations-api/operations.md` From d47f856f75bf6d64fe7a3381a8384aef596935f3 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Thu, 11 Jun 2026 08:58:01 -0600 Subject: [PATCH 2/2] style: format Learn section outline files with prettier Co-Authored-By: Claude Opus 4.8 (1M context) --- plans/learn-section-outline/README.md | 74 +++++++++---------- .../issues/01-deploy-to-fabric.md | 9 ++- .../issues/04-defining-databases-tables.md | 5 +- .../issues/05-loading-data.md | 5 +- .../issues/06-users-and-roles.md | 2 + .../issues/07-querying-interacting.md | 3 + .../issues/08-real-time-intro.md | 2 + .../issues/09-custom-resources.md | 2 + .../issues/10-web-apps.md | 3 + .../issues/12-data-with-replication.md | 6 +- .../issues/13-plugin-development.md | 3 + .../issues/14-running-locally.md | 2 + .../issues/15-running-in-container.md | 5 +- .../issues/16-fabric-deployment.md | 5 +- .../issues/17-manual-replication-setup.md | 5 +- .../issues/18-logging.md | 2 + .../issues/19-analytics-grafana.md | 2 + .../issues/20-certificates.md | 3 + .../issues/21-security-configuration.md | 2 + .../issues/22-compaction.md | 2 + plans/learn-section-outline/issues/23-jobs.md | 2 + 21 files changed, 94 insertions(+), 50 deletions(-) diff --git a/plans/learn-section-outline/README.md b/plans/learn-section-outline/README.md index 894dbc6c..e63a279b 100644 --- a/plans/learn-section-outline/README.md +++ b/plans/learn-section-outline/README.md @@ -45,7 +45,7 @@ learn/ ``` **The entire caching series shipped ahead of plan.** But **Custom Resources** — -declared a *prerequisite* for caching in the original outline — does **not** exist +declared a _prerequisite_ for caching in the original outline — does **not** exist yet. The dependency is currently inverted; Custom Resources (guide #9 below) should be prioritized and the shipped caching guides back-linked to it once it lands. @@ -56,33 +56,34 @@ truth. The deleted legacy `/docs/` page is available for narrative/tutorial fram that may not have survived the reference rewrite. > **Legacy content** lives at git ref **`0f754c5f`** (parent of `01c78b8e`): +> > ```bash > git show 0f754c5f:docs/ > git ls-tree -r --name-only 0f754c5f | grep '^docs/' > ``` -| Topic | Legacy `/docs/` path | Current `reference/` source | -|---|---|---| -| Architecture / core concepts | `foundations/harper-architecture`, `foundations/core-concepts` | `components/overview.md`, `index.md` | -| Applications | `developers/applications/index` | `components/applications.md` | -| Debugging | `developers/applications/debugging` | `configuration/debugging.md` | -| Schema | `developers/applications/defining-schemas` | `database/schema.md` | -| Data Loader | `developers/applications/data-loader` | `database/data-loader.md` | -| Roles | `developers/applications/defining-roles` | `users-and-roles/configuration.md` | -| Users & roles | `developers/security/users-and-roles` | `users-and-roles/overview.md` | -| Custom resources | `developers/applications/index` | `resources/resource-api.md`, `resources/overview.md` | -| Query optimization | `reference/resources/query-optimization` | `resources/query-optimization.md` | -| REST | `developers/rest` | `rest/overview.md`, `rest/querying.md` | -| Real-time | `developers/real-time` | `rest/websockets.md`, `rest/server-sent-events.md` | -| Web apps / routes | `developers/applications/web-applications`, `.../define-routes` | `static-files/overview.md`, `components/nextjs.md`, `fastify-routes/overview.md` | -| Plugins / extensions | `reference/components/plugins`, `.../extensions` | `components/plugin-api.md`, `components/extension-api.md` | -| Replication / sharding | `developers/replication/sharding`, `.../index` | `replication/sharding.md`, `replication/overview.md`, `replication/clustering.md` | -| Logging | `administration/logging/*` | `logging/overview.md`, `logging/configuration.md`, `logging/api.md`, `logging/operations.md` | -| Analytics | `developers/operations-api/analytics` | `analytics/overview.md`, `analytics/operations.md` | -| Certificates | `developers/security/certificate-management`, `.../certificate-verification` | `security/certificate-management.md`, `security/certificate-verification.md` | -| Security config | `developers/security/configuration` | `security/configuration.md`, `http/configuration.md`, `http/tls.md` | -| Compaction | `administration/compact` _(named `compact`)_ | `database/compaction.md` | -| Jobs | `administration/jobs` | `database/jobs.md`, `operations-api/operations.md` | +| Topic | Legacy `/docs/` path | Current `reference/` source | +| ---------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| Architecture / core concepts | `foundations/harper-architecture`, `foundations/core-concepts` | `components/overview.md`, `index.md` | +| Applications | `developers/applications/index` | `components/applications.md` | +| Debugging | `developers/applications/debugging` | `configuration/debugging.md` | +| Schema | `developers/applications/defining-schemas` | `database/schema.md` | +| Data Loader | `developers/applications/data-loader` | `database/data-loader.md` | +| Roles | `developers/applications/defining-roles` | `users-and-roles/configuration.md` | +| Users & roles | `developers/security/users-and-roles` | `users-and-roles/overview.md` | +| Custom resources | `developers/applications/index` | `resources/resource-api.md`, `resources/overview.md` | +| Query optimization | `reference/resources/query-optimization` | `resources/query-optimization.md` | +| REST | `developers/rest` | `rest/overview.md`, `rest/querying.md` | +| Real-time | `developers/real-time` | `rest/websockets.md`, `rest/server-sent-events.md` | +| Web apps / routes | `developers/applications/web-applications`, `.../define-routes` | `static-files/overview.md`, `components/nextjs.md`, `fastify-routes/overview.md` | +| Plugins / extensions | `reference/components/plugins`, `.../extensions` | `components/plugin-api.md`, `components/extension-api.md` | +| Replication / sharding | `developers/replication/sharding`, `.../index` | `replication/sharding.md`, `replication/overview.md`, `replication/clustering.md` | +| Logging | `administration/logging/*` | `logging/overview.md`, `logging/configuration.md`, `logging/api.md`, `logging/operations.md` | +| Analytics | `developers/operations-api/analytics` | `analytics/overview.md`, `analytics/operations.md` | +| Certificates | `developers/security/certificate-management`, `.../certificate-verification` | `security/certificate-management.md`, `security/certificate-verification.md` | +| Security config | `developers/security/configuration` | `security/configuration.md`, `http/configuration.md`, `http/tls.md` | +| Compaction | `administration/compact` _(named `compact`)_ | `database/compaction.md` | +| Jobs | `administration/jobs` | `database/jobs.md`, `operations-api/operations.md` | > **In-guide links** should use the published doc URL form `/reference/v5/...` > (the current docs version), not raw repo paths. Repo paths above are for the @@ -94,24 +95,13 @@ that may not have survived the reference rewrite. intended authoring sequence; the Developers track is a dependency chain. **Getting Started** + 1. Deploy to Fabric -**Developers** (author roughly in order — each builds on the previous) -4. Defining Databases and Tables -5. Loading Data -6. Users & Roles -7. Querying and Interacting with Data -8. Real-Time Data Access Introduction -9. **Custom Resources** — _prioritize; prerequisite for the already-shipped caching guides_ -10. Web Apps -12. Data with Replication -13. Plugin Development - -**Administration** -14. Running Harper Locally · 15. Running Harper in a Container · 16. Fabric -Deployment Guide · 17. Manual / Local Replication Setup · 18. Logging · -19. Analytics & Grafana Plugin · 20. Certificate Management & Verification · -21. Security Configuration · 22. Compaction · 23. Jobs +**Developers** (author roughly in order — each builds on the previous) 4. Defining Databases and Tables 5. Loading Data 6. Users & Roles 7. Querying and Interacting with Data 8. Real-Time Data Access Introduction 9. **Custom Resources** — _prioritize; prerequisite for the already-shipped caching guides_ 10. Web Apps 12. Data with Replication 13. Plugin Development + +**Administration** 14. Running Harper Locally · 15. Running Harper in a Container · 16. Fabric +Deployment Guide · 17. Manual / Local Replication Setup · 18. Logging · 19. Analytics & Grafana Plugin · 20. Certificate Management & Verification · 21. Security Configuration · 22. Compaction · 23. Jobs _(Numbers 2, 3, 11 intentionally absent — already shipped.)_ @@ -119,7 +109,9 @@ Full per-guide scope is in [`issues/`](./issues) — one Markdown file per guide used verbatim as the GitHub issue body in Phase 1. ### Overlaps with existing open issues + Dedupe before/at issue creation — cross-link, and close pure duplicates: + - #16 Fabric Deployment ↔ **#502** (CI/CD Fabric deploy) — strongest overlap; merge. - #1 Deploy to Fabric ↔ #478, #502. - #5 Loading Data / #13 Plugin Dev ↔ **#513** (restart behavior). @@ -129,7 +121,7 @@ Dedupe before/at issue creation — cross-link, and close pure duplicates: ## 5. Conventions - **Template:** every guide follows `learn/_guide-template.mdx` — intro, - *What You Will Learn*, *Prerequisites*, body sections, *Additional Resources*. + _What You Will Learn_, _Prerequisites_, body sections, _Additional Resources_. - **Location:** `learn/
/.mdx` (`getting-started` | `developers` | `administration`). - **Sidebar:** register the new doc in `sidebarsLearn.ts`. Getting Started and @@ -202,6 +194,7 @@ Do them one or a few at a time; respect the §4 ordering (Custom Resources early `git worktree remove "$PWD/.claude/worktrees/learn-"`. ### Guardrails for the agent + - One guide per PR — keep diffs reviewable. - Never invent APIs/behavior: every claim traces to a `reference/` doc or verified example. When unsure, flag it in the PR description rather than guessing. @@ -211,6 +204,7 @@ Do them one or a few at a time; respect the §4 ordering (Custom Resources early the §4 order. ## 8. Open decisions (for maintainers) + - Whether to close/merge #502 into guide #16. - Whether to add a dedicated `learn` label for track-wide filtering (currently `content` only). diff --git a/plans/learn-section-outline/issues/01-deploy-to-fabric.md b/plans/learn-section-outline/issues/01-deploy-to-fabric.md index 2281a7ac..e1ffb436 100644 --- a/plans/learn-section-outline/issues/01-deploy-to-fabric.md +++ b/plans/learn-section-outline/issues/01-deploy-to-fabric.md @@ -1,16 +1,19 @@ -**Section:** Getting Started — third entry, after *Install and Connect Harper* and *Create Your First Application*. +**Section:** Getting Started — third entry, after _Install and Connect Harper_ and _Create Your First Application_. Bridges local development and cloud deployment for first-time Harper developers. ## Goals / Scope + - Expand on quickstart concepts — define "Application" and "Plugin" as first encountered (do not defer to a Core Concepts page). - Add detail when introducing each new concept for the first time. -- Follow `learn/_guide-template.mdx`: structured *What You Will Learn*, *Prerequisites*, *Additional Resources*. +- Follow `learn/_guide-template.mdx`: structured _What You Will Learn_, _Prerequisites_, _Additional Resources_. ## Reference source material + - Architecture & concepts: `reference/components/overview.md`, `reference/index.md` - Legacy narrative (optional): `git show 0f754c5f:docs/foundations/harper-architecture.md`, `git show 0f754c5f:docs/foundations/core-concepts.md` ## Notes + - First-time developer guide — keep conceptual overhead low. -- Related existing issues: #502 (CI/CD deploy guide for Fabric), #478 (Harper deploy behavior). This is the onboarding-level deploy; the *Fabric Deployment Guide* (Administration) is the deeper version. +- Related existing issues: #502 (CI/CD deploy guide for Fabric), #478 (Harper deploy behavior). This is the onboarding-level deploy; the _Fabric Deployment Guide_ (Administration) is the deeper version. diff --git a/plans/learn-section-outline/issues/04-defining-databases-tables.md b/plans/learn-section-outline/issues/04-defining-databases-tables.md index 7dae575b..fb72ca34 100644 --- a/plans/learn-section-outline/issues/04-defining-databases-tables.md +++ b/plans/learn-section-outline/issues/04-defining-databases-tables.md @@ -1,6 +1,7 @@ **Section:** Developers. Evolves the schema system from Getting Started toward interactive examples and broader database/table configuration. ## Goals / Scope + - Build from the schema reference: `reference/database/schema.md`. - Interactive examples: show what custom directives do via `curl`/`fetch`. - Show Operations API usage (e.g. `create_table`) and CLI equivalents — `reference/operations-api/operations.md`, `reference/cli/commands.md`. @@ -10,8 +11,10 @@ - Keep scope lean — complex interaction comes later. ## Reference source material + - `reference/database/schema.md`, `reference/database/overview.md` - Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/defining-schemas.md` ## Notes -- Dependency chain: first Developers-track guide → *Loading Data* → *Users & Roles* → *Querying* → *Real-Time* → *Custom Resources* → *Web Apps*. + +- Dependency chain: first Developers-track guide → _Loading Data_ → _Users & Roles_ → _Querying_ → _Real-Time_ → _Custom Resources_ → _Web Apps_. diff --git a/plans/learn-section-outline/issues/05-loading-data.md b/plans/learn-section-outline/issues/05-loading-data.md index 38a34641..f065f172 100644 --- a/plans/learn-section-outline/issues/05-loading-data.md +++ b/plans/learn-section-outline/issues/05-loading-data.md @@ -1,14 +1,17 @@ -**Section:** Developers. Builds on the tables from *Defining Databases and Tables*; demonstrates bulk loading via the Data Loader plugin and other mechanisms. +**Section:** Developers. Builds on the tables from _Defining Databases and Tables_; demonstrates bulk loading via the Data Loader plugin and other mechanisms. ## Goals / Scope + - Multiple ways to load data, kept approachable (no deep auth/roles yet — that is the next guide). - Use Data Loader to explain the Harper application lifecycle: it survives restarts → frame Harper as a long-running system and how to think about lifecycle in dev vs production. - Full end-to-end: load data → query with basic REST / Operations / CLI. - Audience is ~4 guides in: comfortable with key concepts, not experts. ## Reference source material + - `reference/database/data-loader.md` - Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/data-loader.md` ## Notes + - Related existing issue #513 (Document Harper restart behavior and guarantees) covers the lifecycle/restart framing — cross-link or fold in. diff --git a/plans/learn-section-outline/issues/06-users-and-roles.md b/plans/learn-section-outline/issues/06-users-and-roles.md index 86f02be3..e201fb47 100644 --- a/plans/learn-section-outline/issues/06-users-and-roles.md +++ b/plans/learn-section-outline/issues/06-users-and-roles.md @@ -1,6 +1,7 @@ **Section:** Developers. Comprehensive guide to Harper's built-in User and Role system, scoping what it is and is not for. ## Goals / Scope + - Iterate on the users-and-roles reference: `reference/users-and-roles/overview.md`, `reference/users-and-roles/configuration.md`, `reference/users-and-roles/operations.md`. - Explain how roles matter specifically to application developers. - Define clearly: native Users & Roles is for **database permissions**, not for building custom user/auth systems. @@ -9,5 +10,6 @@ - Link to security and authentication guides. ## Reference source material + - `reference/users-and-roles/*` - Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/defining-roles.md`, `git show 0f754c5f:docs/developers/security/users-and-roles.md` diff --git a/plans/learn-section-outline/issues/07-querying-interacting.md b/plans/learn-section-outline/issues/07-querying-interacting.md index 7b52f143..ec502745 100644 --- a/plans/learn-section-outline/issues/07-querying-interacting.md +++ b/plans/learn-section-outline/issues/07-querying-interacting.md @@ -1,14 +1,17 @@ **Section:** Developers. Advanced querying, building on REST + Resource API basics. ## Goals / Scope + - Advanced scenarios: relational tables, computed properties, HNSW indexing. - Query optimization (intro-level; deeper guide possible later). - Relational data examples if not covered earlier. - Querying for computed properties and other complex DB scenarios. ## Reference source material + - `reference/resources/query-optimization.md`, `reference/rest/querying.md`, `reference/rest/overview.md` - Legacy narrative (optional): `git show 0f754c5f:docs/developers/rest.md` ## Notes + - Related existing issue #490 (relational selects and conditions in `search_by_conditions`). Cross-link. diff --git a/plans/learn-section-outline/issues/08-real-time-intro.md b/plans/learn-section-outline/issues/08-real-time-intro.md index a5f2e823..2deea73e 100644 --- a/plans/learn-section-outline/issues/08-real-time-intro.md +++ b/plans/learn-section-outline/issues/08-real-time-intro.md @@ -1,11 +1,13 @@ **Section:** Developers. Introduces real-time data access patterns, including WebSockets, with both basic tables and custom resources. ## Goals / Scope + - Demonstrate WebSockets and other real-time mechanisms. - Show usage with both basic tables and custom resources. - Consider GIFs / video embeds to illustrate live interactivity. - Keep scope simple — complex scenarios (e.g. live chat) come after Custom Resources and the (shipped) Caching guides. ## Reference source material + - `reference/rest/websockets.md`, `reference/rest/server-sent-events.md`, `reference/mqtt/overview.md` - Legacy narrative (optional): `git show 0f754c5f:docs/developers/real-time.md` diff --git a/plans/learn-section-outline/issues/09-custom-resources.md b/plans/learn-section-outline/issues/09-custom-resources.md index c4034364..daa7b7b1 100644 --- a/plans/learn-section-outline/issues/09-custom-resources.md +++ b/plans/learn-section-outline/issues/09-custom-resources.md @@ -1,6 +1,7 @@ **Section:** Developers. Deep-dive on one of Harper's most important features. ## Goals / Scope + - Build on Getting Started + the Resource API reference: `reference/resources/resource-api.md`, `reference/resources/overview.md`, `reference/components/applications.md`. - Show how requests of all forms (REST, Operations, CLI, WebSocket) work with custom resources. - **Resource API v2 only.** @@ -9,4 +10,5 @@ - Example can be simple but must demonstrate the full feature surface. ## Notes + - **Priority: elevate this.** The already-shipped caching guides (`learn/developers/caching-*.mdx`) treat Custom Resources as a prerequisite that does not exist yet. This back-fills the gap — add a back-link from the caching guides once this lands. diff --git a/plans/learn-section-outline/issues/10-web-apps.md b/plans/learn-section-outline/issues/10-web-apps.md index 17ad3346..66f70e99 100644 --- a/plans/learn-section-outline/issues/10-web-apps.md +++ b/plans/learn-section-outline/issues/10-web-apps.md @@ -1,14 +1,17 @@ **Section:** Developers. From simple static hosting to more complex server-side setups. ## Goals / Scope + - **Part 1 — Static hosting:** static plugin as the starting point for client-side apps; working React + Vite example; link to a collection of static framework templates. - **Part 2 — Complex web apps:** introduce plugin-development concepts (without a full plugin guide yet); show existing web app plugins; demonstrate getting started with Next.js or similar using existing plugins. - Discuss server-side code (direct Harper resource access) vs client-side (networking interfaces only). - Dev server and deployment basics; link to the Administration guide for depth. ## Reference source material + - `reference/static-files/overview.md`, `reference/components/nextjs.md`, `reference/fastify-routes/overview.md` - Legacy narrative (optional): `git show 0f754c5f:docs/developers/applications/web-applications.md` ## Notes + - The `@harperfast/nextjs` plugin docs were recently updated (#505) — reference them. diff --git a/plans/learn-section-outline/issues/12-data-with-replication.md b/plans/learn-section-outline/issues/12-data-with-replication.md index f24ac3cd..a53a271b 100644 --- a/plans/learn-section-outline/issues/12-data-with-replication.md +++ b/plans/learn-section-outline/issues/12-data-with-replication.md @@ -1,11 +1,13 @@ -**Section:** Developers. Goes deeper on replication, building on the brief intro from *Defining Databases and Tables*. +**Section:** Developers. Goes deeper on replication, building on the brief intro from _Defining Databases and Tables_. ## Goals / Scope + - Expand on the replication reference: `reference/replication/sharding.md`, `reference/replication/overview.md`, `reference/replication/clustering.md`. - Cover more complex replication scenarios. -- Link to the Administration-side *Manual / Local Replication Setup* guide. +- Link to the Administration-side _Manual / Local Replication Setup_ guide. - Include utility scripts for local setup. - Notes on replication availability/limitations in v5. ## Notes + - Related existing issues: #510 (clustering troubleshooting), #511 (clustering TLS best practices). Cross-link. diff --git a/plans/learn-section-outline/issues/13-plugin-development.md b/plans/learn-section-outline/issues/13-plugin-development.md index 9d2833c5..6ac2dd57 100644 --- a/plans/learn-section-outline/issues/13-plugin-development.md +++ b/plans/learn-section-outline/issues/13-plugin-development.md @@ -1,12 +1,15 @@ **Section:** Developers. Standalone guide for developing custom Harper plugins using the new plugin API. ## Goals / Scope + - Walk through the new plugin API in detail. - Go deep on plugin and application lifecycle. - Demonstrate the restart request process. ## Reference source material + - `reference/components/plugin-api.md`, `reference/components/extension-api.md`, `reference/components/overview.md` ## Notes + - Related existing issue #513 (restart behavior/guarantees) — the restart-request process overlaps; cross-link. diff --git a/plans/learn-section-outline/issues/14-running-locally.md b/plans/learn-section-outline/issues/14-running-locally.md index c059a70c..cb9bf023 100644 --- a/plans/learn-section-outline/issues/14-running-locally.md +++ b/plans/learn-section-outline/issues/14-running-locally.md @@ -1,6 +1,7 @@ **Section:** Administration. Running Harper locally for development. ## Goals / Scope + - v5: split between "standard installation" and "from source". - v4: installation only. - Multiple install configurations. @@ -8,5 +9,6 @@ - Configuration tips and defaults for dev vs production. ## Reference source material + - `reference/cli/overview.md`, `reference/configuration/overview.md`, `reference/configuration/options.md` - Existing guide to build on: `learn/getting-started/install-and-connect-harper.mdx` diff --git a/plans/learn-section-outline/issues/15-running-in-container.md b/plans/learn-section-outline/issues/15-running-in-container.md index 7576845b..323848f9 100644 --- a/plans/learn-section-outline/issues/15-running-in-container.md +++ b/plans/learn-section-outline/issues/15-running-in-container.md @@ -1,10 +1,13 @@ -**Section:** Administration. Like *Running Harper Locally* but scoped to containers. +**Section:** Administration. Like _Running Harper Locally_ but scoped to containers. ## Goals / Scope + - Container-specific considerations: port forwarding, environment variables, mounted dev dir, etc. ## Reference source material + - `reference/environment-variables/overview.md`, `reference/configuration/options.md` ## Notes + - Reference the v5 Docker image name change (#476, closed) so the image name is correct. diff --git a/plans/learn-section-outline/issues/16-fabric-deployment.md b/plans/learn-section-outline/issues/16-fabric-deployment.md index a8a0c7f0..4d363ff0 100644 --- a/plans/learn-section-outline/issues/16-fabric-deployment.md +++ b/plans/learn-section-outline/issues/16-fabric-deployment.md @@ -1,12 +1,15 @@ **Section:** Administration. Deploying and working with Harper on Fabric, developer-focused. ## Goals / Scope + - Pull from existing Fabric docs (`fabric/`) and adapt to the Learn guide format. - Developer-focused: what is possible with a Fabric instance (e.g. deploying from CLI). - UI-based Fabric docs stay in the Fabric section; this guide is CLI/developer-facing. ## Reference source material + - `fabric/` (existing Fabric section), `reference/cli/commands.md` ## Notes -- **Strong overlap with existing issue #502** ("Add a CI/CD deploy guide for Harper Fabric") — recommend merging/closing #502 into this, or scoping #502 as the CI/CD half. Also relates to #478 and the Getting Started *Deploy to Fabric* guide. + +- **Strong overlap with existing issue #502** ("Add a CI/CD deploy guide for Harper Fabric") — recommend merging/closing #502 into this, or scoping #502 as the CI/CD half. Also relates to #478 and the Getting Started _Deploy to Fabric_ guide. diff --git a/plans/learn-section-outline/issues/17-manual-replication-setup.md b/plans/learn-section-outline/issues/17-manual-replication-setup.md index 62e36ae9..c14aa027 100644 --- a/plans/learn-section-outline/issues/17-manual-replication-setup.md +++ b/plans/learn-section-outline/issues/17-manual-replication-setup.md @@ -1,11 +1,14 @@ -**Section:** Administration. Admin-side guide for setting up replication manually/locally. Complements the developer-side *Data with Replication* guide. +**Section:** Administration. Admin-side guide for setting up replication manually/locally. Complements the developer-side _Data with Replication_ guide. ## Goals / Scope + - Feature support details specific to v5. - Helpful utility scripts for local setup. ## Reference source material + - `reference/replication/overview.md`, `reference/replication/clustering.md` ## Notes + - Related existing issues: #510 (clustering troubleshooting), #511 (clustering TLS). Cross-link. diff --git a/plans/learn-section-outline/issues/18-logging.md b/plans/learn-section-outline/issues/18-logging.md index 9618921c..77729dc1 100644 --- a/plans/learn-section-outline/issues/18-logging.md +++ b/plans/learn-section-outline/issues/18-logging.md @@ -1,11 +1,13 @@ **Section:** Administration. Turns existing Logging reference content into a practical usage guide. ## Goals / Scope + - Iterate on the logging reference: `reference/logging/overview.md`, `reference/logging/configuration.md`, `reference/logging/api.md`, `reference/logging/operations.md`. - Start simple (basic config/usage), progress to advanced (log rotation, etc.). - Possibly third-party log consumers (DataDog, etc.) — may warrant follow-on guides. - Ensure structured reference docs for logging APIs/config exist or are linked. ## Reference source material + - `reference/logging/*` - Legacy narrative (optional): `git show 0f754c5f:docs/administration/logging/index.md` diff --git a/plans/learn-section-outline/issues/19-analytics-grafana.md b/plans/learn-section-outline/issues/19-analytics-grafana.md index 6d68d08e..6385e95a 100644 --- a/plans/learn-section-outline/issues/19-analytics-grafana.md +++ b/plans/learn-section-outline/issues/19-analytics-grafana.md @@ -1,9 +1,11 @@ **Section:** Administration. Understanding and using Harper's analytics features, with Grafana as the primary demo. ## Goals / Scope + - Deep dive on Harper analytics features. - Grafana as the key demonstration. - Other third-party integrations could live in separate guides. ## Reference source material + - `reference/analytics/overview.md`, `reference/analytics/operations.md` diff --git a/plans/learn-section-outline/issues/20-certificates.md b/plans/learn-section-outline/issues/20-certificates.md index cc1e29b7..37ef0498 100644 --- a/plans/learn-section-outline/issues/20-certificates.md +++ b/plans/learn-section-outline/issues/20-certificates.md @@ -1,13 +1,16 @@ **Section:** Administration. Practical usage guide for certificate management and verification, evolving reference content into an interactive guide. ## Goals / Scope + - Iterate on the security reference: `reference/security/certificate-management.md`, `reference/security/certificate-verification.md`. - Walk through actual setup steps, not just reference. - Demonstrate how certificates affect requests via `fetch`/`curl`. - Consider splitting into two guides depending on complexity. ## Reference source material + - `reference/security/certificate-management.md`, `reference/security/certificate-verification.md`, `reference/http/tls.md` ## Notes + - Related existing issue #511 (clustering TLS certificate best practices). Cross-link. diff --git a/plans/learn-section-outline/issues/21-security-configuration.md b/plans/learn-section-outline/issues/21-security-configuration.md index 6875a1f9..83e3700f 100644 --- a/plans/learn-section-outline/issues/21-security-configuration.md +++ b/plans/learn-section-outline/issues/21-security-configuration.md @@ -1,8 +1,10 @@ **Section:** Administration. Configuring Harper's security features (CORS, SSL) and how settings affect runtime behavior. ## Goals / Scope + - Walk through CORS and SSL config with concrete before/after request examples. - Use real `curl`/`fetch` examples to show the impact of each setting. ## Reference source material + - `reference/security/configuration.md`, `reference/security/overview.md`, `reference/http/configuration.md`, `reference/http/tls.md` diff --git a/plans/learn-section-outline/issues/22-compaction.md b/plans/learn-section-outline/issues/22-compaction.md index 4da60423..0877ccd6 100644 --- a/plans/learn-section-outline/issues/22-compaction.md +++ b/plans/learn-section-outline/issues/22-compaction.md @@ -1,8 +1,10 @@ **Section:** Administration. Practical guide to Compaction, expanding reference content with a full working example. ## Goals / Scope + - Iterate on the compaction reference: `reference/database/compaction.md`. - Full end-to-end example with requests; do not re-explain schemas/data loading (link to those guides) but use them for context. ## Reference source material + - `reference/database/compaction.md` diff --git a/plans/learn-section-outline/issues/23-jobs.md b/plans/learn-section-outline/issues/23-jobs.md index 9a1844a5..394559ec 100644 --- a/plans/learn-section-outline/issues/23-jobs.md +++ b/plans/learn-section-outline/issues/23-jobs.md @@ -1,8 +1,10 @@ **Section:** Administration. Practical guide to Harper Jobs with full, interactive examples. ## Goals / Scope + - Iterate on the jobs reference: `reference/database/jobs.md`. - Demonstrate job operations end-to-end with complete working examples. ## Reference source material + - `reference/database/jobs.md`, `reference/operations-api/operations.md`