docs: regenerate rules from documentation@7e373fa

[harper-skills-sync]

Automated regeneration of docs-driven skill rules, now synced to HarperFast/documentation@7e373fa.

Why these rules changed

Each rule regenerated because its source content differs from the docs commit it was last synced from. The trigger commit is not necessarily what changed a given rule — drift accumulates across every docs commit since the rule’s recorded baseline (below).

• defining-relationships — last synced from docs@4fe4c9c
• vector-indexing — last synced from docs@4fe4c9c
• querying-rest-apis — last synced from docs@b7fbdda
• programmatic-table-requests — last synced from docs@be709f9
• v5-upgrade — last synced from docs@de2aaf1

Docs commits since baseline (4fe4c9c..7e373fa)

7e373fa3	fix: correct two example bugs caught by skills#70's review
dcd7d7c5	docs(static-files): document before/after handler ordering (#562)
c5be2f9c	docs: collection-aware record-scoped allowRead example (super composition + subscribe re-auth)
0bf9867d	docs: subscriptions now filter delivery per event through record-scoped allowRead (#1419)
14daaebe	Rework record-level access control docs: record-scoped allowRead override replaces allowReadRecord
8dd5a54a	docs review: state boolean return contract for vectorFilter and allowReadRecord
cdf55c7a	Document filtered vector search: predicate-aware HNSW traversal, vectorFilter, allowReadRecord, filterExpansion (5.2)
de2aaf1c	gitignore .claude directory
1ca00981	Document threads.preload config option (#561)
dbb3c182	docs: fix incorrect @relation directive to @relationship (#577)
a6bf98c8	Fix Resource post/put/patch data type + document search sort + content-type table (#495)
fda31e10	docs(replication): use hostname in controlled-flow route example (#555)
1e54b713	docs(configuration): document replication.blobSendDrainTimeout (#569)
8c535e4a	Correct custom mcpTools auth wording: invocable anonymously, no login gate
b9c98adc	Document the perClientBurst one-token floor; version refs 5.2.0 (merged to main)
0ac01aa5	Add race-safety caveat to the quota-hook docs (harper#1633 fast-follow)
bb5871e9	Correct cache-disposition docs: target.loadedFromSource only (context mirror reverted) (#570)
27fb8cc8	Document MCP per-client rate limiting and the durable quota hook (harper#1633)
9e49f6ca	docs(config): replicated set_configuration ships in 5.2, not 5.1
a401477e	docs(resources): document loadedFromSource cache disposition (harper#1571/#1575)
e5b276f1	docs(analytics): tighten get_analytics read-behavior wording
d416e162	docs(analytics): note get_analytics reads without a consistent snapshot
8d9710c4	docs(ops): correct stale restart_service service list to v5 values
894f9dfa	docs(config): document replicated: true on set_configuration (HarperFast/harper#1556)
0011798f	docs(models): document config-selectable backends (backend: <module>)
2a761eee	docs(models): clarify fallback-policy and no-candidates wording (review)
774fee32	docs(models): routing shipped in v5.1.15; drop breaking-change release note
055ae36d	docs(models): fix release-note cross-links to reference (add /v5/ segment)
797a05e2	docs(models): namespace registration API + document routing & fallback
d37c9847	docs(models): document registerBackend / defineBackend custom backends (#554)
f37a8c40	docs(resources): use static verb handlers in path-parameter examples
60f6d2e4	docs(resources): document parameterised resource paths and `static path`
3edab38c	docs: thrown Response/status now honored; Long bound; repeatable-read wording
5675b32f	docs: clarify concurrency, read consistency, Long/BigInt, and resource status codes
1172ec68	docs(meta): document issue types, area labels, and release milestones (#546)
25e2580f	chore(intake): issue types, simplified forms, and config (#545)
be709f99	docs(database): add data-safety note for programmatic writes/deletes (#542)
fa62588d	docs: clarify Harper APIs are one live process-wide instance; SSR data access (#543)
e66d44b0	docs(sse): lead with single-method static async *connect(target)
ce0ab713	docs(resources): document relationship select and join behavior (#537)
9d8bf128	docs: restore v5 resource-handler nuance and fix blob handler consistency (#541)
ba576f81	docs(sse): document reading the request in static connect()

Produced by .github/workflows/generate.yaml. Review the diff as you would any rule change — the generator reads the docs build output and rewrites mode: generate / imports mode: direct rule bodies, then reassembles AGENTS.md. See docs/plans/docs-driven-skills.md.

🤖 Generated with Claude Code

[kriszyp]

Nice work on this regeneration — the vast majority of it is a faithful, verified-accurate resync. I checked several claims directly against ~/dev/harper source (allowFullScan, the exact HdbError text, FIQL type-prefix coercion, the ==<value>* wildcard) and they all check out. The @relation → @relationship typo fix in querying-rest-apis.md in particular is a genuine, valuable correction — good catch by the generator there.

That said, I found two real API-accuracy bugs that made it into this PR, both regressions vs. the previously-synced text:

1. Many-to-many example points from at a field that doesn't exist
defining-relationships.md:100 (also AGENTS.md:300):

type Product @table @export {
	id: Long @primaryKey
	name: String
	resellerIds: [Long] @indexed
	resellers: [Reseller] @relationship(from: "resellerId")
}

The schema declares resellerIds (array), but the relationship is wired to the singular resellerId, which doesn't exist on the record. Verified against resources/graphql.ts:216-221 (no name normalization on directive args) and resources/search.ts:578 (record[attribute.relationship.from]?.filter?.(...) — literal property lookup). An agent copying this verbatim gets a relationship that silently resolves to nothing. The pre-PR skill text had this right (from: resellerIds, matching the array attribute).

2. Foreign-key-to-foreign-key join mislabeled as "many-to-many"
defining-relationships.md:59 (also AGENTS.md:259) now reads "...useful for many-to-many relationships joining on non-primary-key attributes," but the accompanying example (OrderItem.product: Product @relationship(from: productSku, to: sku)) is a scalar field — one-to-one/many-to-one, not many-to-many. An agent following this rule for a genuine many-to-many case would produce a relationship that can't hold multiple related records.

Root cause is upstream, not in this PR. Both bugs trace directly to documentation@dbb3c18 itself:

• Bug 1: reference/rest/querying.md:227-228 has the same resellerIds/resellerId mismatch — while that same repo's reference/database/schema.md:378-382 has the correct, internally-consistent version (networkIds / @relationship(from: networkIds)). The generator just happened to pull the buggy copy instead of the correct one sitting right there in the same source set.
• Bug 2: reference/database/schema.md:398-400 states the identical "useful for many-to-many relationships" claim against the same scalar OrderItem/sku example.

This regeneration faithfully reproduced what's in the source docs — it's not a generator hallucination. The durable fix belongs in HarperFast/documentation so it doesn't keep re-propagating into every future skill regen (this would be at least the second consecutive regen cycle reintroducing a relationship-example bug). Worth noting the same resellerId/resellerIds bug also already exists unchanged in querying-rest-apis.md:100 and AGENTS.md:1042 from prior syncs, so a doc-repo fix would need a follow-up regen to fully clear it everywhere.

Reviewer's call on how to sequence this: hold this PR for the upstream documentation fix and let the next regen pick it up clean, or take a quick manual patch here now (swap in the networkIds-style example / soften the many-to-many claim) and accept it'll need reconciling again once upstream is fixed. Either way, flagging so it doesn't quietly ship as agent-facing guidance.

— Claude (Sonnet 5), reviewed via review-queue

[kriszyp]

Re-review of the regen (now documentation@de2aaf1)

Thanks for the regen — one real fix landed, but a known blocker not only persisted, it regressed. Recommend holding this (do not merge) until the upstream doc is corrected, since merging ships a known agent-facing rule bug.

What's good

The @relation → @relationship directive typo is now fixed and correctly propagated (querying-rest-apis.md:204). @relationship is the only registered directive (graphql.ts:45, dispatched at :216); @relation was silently ignored. This is the genuine, valuable change in the PR.

Blocker — regressed: many-to-many array example wires a nonexistent attribute

The array declares resellerIds but the directive now says from: "resellerId" (singular), across all 4 locations:

• defining-relationships.md:100
• querying-rest-apis.md:192
• AGENTS.md:300 and AGENTS.md:1065

Worse: last pass defining-relationships.md still carried one correct copy (@relationship(from: resellerIds)). This regen deleted it and replaced it with the broken singular form in a new "How It Works" step 6 — so now every copy is wrong.

Why it's really broken (verified against live ~/dev/harper 17ab8efd8): graphql.ts:216-221 stores directive args verbatim (relationshipDefinition[arg.name.value] = arg.value.value) with no name normalization, and search.ts resolves the array many-to-many path by literal property lookup — record[attribute.relationship.from]?.filter?.(...) at search.ts:578 and { attribute: attribute.relationship.from, value: relatedEntry } at search.ts:187. With from: "resellerId" that reads record.resellerId, which is undefined since the schema only defines resellerIds. An agent copying this gets a relationship that silently resolves to nothing.

Significant — scalar from+to join still mislabeled as many-to-many

• defining-relationships.md:59, AGENTS.md:259

The rule now claims @relationship(from: attribute, to: attribute) "supports many-to-many relationships on non-primary-key attributes", but the paired example (OrderItem.product: Product @relationship(from: productSku, to: sku)) uses two scalar fields — that's many-to-one. Cardinality in Harper is decided by whether the referenced attribute is an array: search.ts:180 sets isManyToMany = Boolean(findAttribute(relatedTable.attributes, attribute.relationship.to)?.elements). A scalar from/to join can't be many-to-many.

Root cause is upstream — fix in documentation, not here

Both issues are faithfully propagated from the canonical source. A skill-side patch would just drift back on the next regen. The fix needs to land in HarperFast/documentation:

• reference/rest/querying.md — the resellerId/resellerIds mismatch
• align with the correct many-to-many pattern already in reference/database/schema.md

This is the second consecutive regen (skills#69, now #70) to ship a relationship-example inaccuracy. Worth adding a generator-side lint before regeneration: "every attribute referenced in a from:/to: example must appear in the adjacent schema block" would have caught the blocker mechanically, and an "array-vs-scalar" heuristic could flag the many-to-many mislabel.

— Claude (Sonnet 5), on behalf of Kris, via review-queue

[kriszyp]

I think the upstream doc fixes have been merged, think you can re-generate?

[kriszyp]

This is the same resellerId/resellerIds mismatch flagged in the last two review rounds on this PR, and it's regressed further: the schema declares the array resellerIds, but from: references the singular resellerId, which doesn't exist on the record. This regen actually deleted the one remaining correct copy of this example (from: resellerIds, unquoted) that survived in a prior sync, and replaced it with this broken form in the new "How It Works" step 6 — so now every copy in the repo is wrong. An agent copying this verbatim gets a relationship that silently resolves to nothing.

Root cause is upstream: HarperFast/documentation reference/rest/querying.md:227-228 has this exact mismatch, while reference/database/schema.md:378-382 has the correct pattern (networkIds / @relationship(from: networkIds)) right next to it. Recommend fixing upstream and re-running the regen rather than patching here, since this file is mode: generate.

[kriszyp]

This code block calls transaction(() => Table.get(target)) but the import above (line 75) only imports getContext — transaction is undefined here, so this throws ReferenceError if copied as-is. origin/main (pre-PR) had import { getContext, transaction } from 'harper';; this regen dropped transaction from the import while keeping the call, which is a real regression versus the previously-synced text. Same issue repeats at line 182 in this file and in AGENTS.md:2639 / AGENTS.md:2741.

Root cause is upstream: HarperFast/documentation release-notes/v5-lincoln/v5-migration.md:87,95 has the identical incomplete import + undeclared call. The old skill text had silently corrected this; this regen overwrote the fix with the faithful (broken) copy.

[kriszyp]

This step describes @relationship(from: attribute, to: attribute) as "useful for many-to-many relationships," but the paired example (OrderItem.product: Product @relationship(from: productSku, to: sku)) uses two scalar fields — that's many-to-one, not many-to-many (cardinality is determined by whether the to-side attribute is an array). Flagged in the prior review round on this PR and still unresolved. Root cause: documentation reference/database/schema.md:398-400 makes the same claim against the same scalar example.

[kriszyp]

Typo: "support support" (duplicate word) — "Only indexes created with null indexing support support this".