Skip to content

docs: fill Harper-specific gaps surfaced by skills reverse-scan#500

Merged
Ethan-Arrowood merged 1 commit into
mainfrom
kris/docs-skill-gaps
May 26, 2026
Merged

docs: fill Harper-specific gaps surfaced by skills reverse-scan#500
Ethan-Arrowood merged 1 commit into
mainfrom
kris/docs-skill-gaps

Conversation

@kriszyp
Copy link
Copy Markdown
Member

@kriszyp kriszyp commented May 26, 2026

Summary

A reverse gap-scan of the harper-best-practices skill rules against the docs surfaced Harper-specific patterns the rules teach but the docs don't. The first migrated rule (vector-indexing) lost two such patterns when it was regenerated from reference/database/schema.md#vector-indexing — this PR closes those gaps and several more so the docs-driven pipeline can take other rules without quality regressions.

Each addition was verified against Harper core source before documenting; nothing here is invented.

Changes

  • Vector indexing (reference/database/schema.md): distance-threshold filter (conditions[].target + comparator: 'lt') and the $distance special select field. Closes the regression introduced by feat: Phase 2 — docs-driven rule generator (generate + direct modes) skills#38.
  • Blob handling (reference/database/api.md): full BlobCreationOptions table (type, size, compress, flush, saveBeforeCommit), base64-from-JSON intake pattern, and the standard Content-Type + body: blob response shape for serving binary.
  • getCurrentUser() + Session/Login from a Resource (reference/resources/resource-api.md): documents getCurrentUser(), Context.login, and Context.session.delete so custom Resources can implement sign-in flows.
  • JWT issuance from a custom Resource (reference/security/jwt-authentication.md): adds an IssueTokens / RefreshJWT recipe using server.operation() (rather than reaching into system tables). Closes Document JWT issuance via databases.system.hdb_user.operation #501.
  • $distance in Query Object (reference/resources/resource-api.md): added alongside $id and $updatedtime in the select reference.
  • Resource routing via export shape (reference/resources/overview.md): a table mapping export class Foo, export const Bar = { Foo }, and export const bar = { 'foo-baz': Foo } to the resulting URLs, plus a note that path matching is case-sensitive.
  • Extending tables (reference/resources/overview.md): explicit "omit @export" guidance and the super.* call convention.
  • TypeScript support (reference/components/javascript-environment.md): Harper's Node-native type stripping — Node ≥ 22.6, .ts source files, explicit .ts in local imports, jsResource glob.
  • Logging (reference/logging/api.md): describe console capture semantics accurately (stdout/stderr interception, not method→level mapping).
  • Fabric ↔ CLI (fabric/cluster-creation-management.md): pointer to harper login <Application URL> (introduced in Login cli #491) so new cluster users discover the CLI entry point; defers full CI/CD setup to the dedicated guide planned in Add a CI/CD deploy guide for Harper Fabric #502.
  • Plugins listing (reference/components/overview.md): added @harperfast/vite-plugin to Known Custom Components; per the convention that plugins own their own docs, this is a link-out, not a duplicated page.

Closes

Follow-ups (filed separately)

Test plan

  • npm run format:check clean
  • npm run typecheck clean
  • npm run build succeeds with no broken links
  • Spot-check rendered pages for layout and anchor targets (reviewer)

🤖 Drafted by Claude (Opus 4.7), on behalf of @kriszyp

@github-actions
Copy link
Copy Markdown

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-500

This preview will update automatically when you push new commits.

@kriszyp kriszyp force-pushed the kris/docs-skill-gaps branch from 41dd875 to f7cb0a7 Compare May 26, 2026 22:36
@github-actions github-actions Bot temporarily deployed to pr-500 May 26, 2026 22:38 Inactive
@github-actions
Copy link
Copy Markdown

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-500

This preview will update automatically when you push new commits.

@kriszyp kriszyp force-pushed the kris/docs-skill-gaps branch from f7cb0a7 to 527b66e Compare May 26, 2026 22:39
@github-actions github-actions Bot temporarily deployed to pr-500 May 26, 2026 22:41 Inactive
@github-actions
Copy link
Copy Markdown

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-500

This preview will update automatically when you push new commits.

Add agent-facing patterns that were present in the harper-best-practices
skill rules but not in the docs, so those rules can be migrated to the
docs-driven generation pipeline without losing content.

- Vector indexing: distance-threshold filter (conditions[].target with
  comparator) and the $distance special select field
- Blob handling: full BlobCreationOptions table (type, size, compress,
  flush), base64-from-JSON intake pattern, and the standard response
  shape for serving binary
- Resource auth: getCurrentUser(), allowRead/Update/Create/Delete,
  Context.login / session.delete, loadAsInstance static
- $distance documented in the Query Object select reference
- Resource routing via export shape (export class vs object key forms),
  case-sensitive path matching
- Schema: @Allow field directive
- TypeScript: type-stripping support, Node >=22.6, .ts extension import
  requirement, jsResource glob
- Extending tables: explicit "omit @export" guidance and super.* call
  convention
- Logging: clarify loggerWithTag is a method alias on logger (not a
  direct export), describe console capture semantics accurately
- Fabric: link the Application URL surface in Fabric Studio to the
  HARPER_CLI_TARGET env var used by the CLI
- Components: add @harperfast/vite-plugin to Known Custom Components

Verified against Harper core source (resources/Resource.ts,
resources/Table.ts, resources/blob.ts, utility/logging/harper_logger.ts,
schema.graphql) before documenting.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@kriszyp kriszyp force-pushed the kris/docs-skill-gaps branch from 527b66e to 9c02ed6 Compare May 26, 2026 22:42
@kriszyp kriszyp marked this pull request as ready for review May 26, 2026 22:42
@kriszyp kriszyp requested a review from a team as a code owner May 26, 2026 22:42
@github-actions github-actions Bot temporarily deployed to pr-500 May 26, 2026 22:44 Inactive
@github-actions
Copy link
Copy Markdown

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-500

This preview will update automatically when you push new commits.

@Ethan-Arrowood
Copy link
Copy Markdown
Member

When I merge this - we should see the cross-repo trigger happen 🤞

@Ethan-Arrowood Ethan-Arrowood merged commit 6d4a30c into main May 26, 2026
7 checks passed
@Ethan-Arrowood Ethan-Arrowood deleted the kris/docs-skill-gaps branch May 26, 2026 23:13
@github-actions
Copy link
Copy Markdown

🧹 Preview Cleanup

The preview deployment for this PR has been removed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document JWT issuance via databases.system.hdb_user.operation

2 participants