docs: fill Harper-specific gaps surfaced by skills reverse-scan#500
Conversation
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-500 This preview will update automatically when you push new commits. |
41dd875 to
f7cb0a7
Compare
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-500 This preview will update automatically when you push new commits. |
f7cb0a7 to
527b66e
Compare
🚀 Preview DeploymentYour 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>
527b66e to
9c02ed6
Compare
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-500 This preview will update automatically when you push new commits. |
|
When I merge this - we should see the cross-repo trigger happen 🤞 |
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
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
reference/database/schema.md): distance-threshold filter (conditions[].target+comparator: 'lt') and the$distancespecial select field. Closes the regression introduced by feat: Phase 2 — docs-driven rule generator (generate + direct modes) skills#38.reference/database/api.md): fullBlobCreationOptionstable (type,size,compress,flush,saveBeforeCommit), base64-from-JSON intake pattern, and the standardContent-Type+body: blobresponse shape for serving binary.getCurrentUser()+ Session/Login from a Resource (reference/resources/resource-api.md): documentsgetCurrentUser(),Context.login, andContext.session.deleteso custom Resources can implement sign-in flows.reference/security/jwt-authentication.md): adds anIssueTokens/RefreshJWTrecipe usingserver.operation()(rather than reaching into system tables). Closes Document JWT issuance via databases.system.hdb_user.operation #501.$distancein Query Object (reference/resources/resource-api.md): added alongside$idand$updatedtimein theselectreference.reference/resources/overview.md): a table mappingexport class Foo,export const Bar = { Foo }, andexport const bar = { 'foo-baz': Foo }to the resulting URLs, plus a note that path matching is case-sensitive.reference/resources/overview.md): explicit "omit@export" guidance and thesuper.*call convention.reference/components/javascript-environment.md): Harper's Node-native type stripping — Node ≥ 22.6,.tssource files, explicit.tsin local imports,jsResourceglob.reference/logging/api.md): describe console capture semantics accurately (stdout/stderr interception, not method→level mapping).fabric/cluster-creation-management.md): pointer toharper 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.reference/components/overview.md): added@harperfast/vite-pluginto Known Custom Components; per the convention that plugins own their own docs, this is a link-out, not a duplicated page.Closes
server.operation)Follow-ups (filed separately)
@harperdbvs@harperfastnamespace usagegraphql.config.yml@allowdirective is parsed but not enforced; finish or removevector-indexingmust_coverafter this lands@authdirective referenceloggerWithTagis not a direct export from 'harper' skills#42 — fixloggerWithTagimport (should belogger.withTag())Test plan
npm run format:checkcleannpm run typecheckcleannpm run buildsucceeds with no broken links🤖 Drafted by Claude (Opus 4.7), on behalf of @kriszyp