ci: documentation-boundary rule; capture .env-deploys-to-fabric

[heskew]

Summary

Two related tunings driven by the #55 review rounds (the env-vars docs PR that went through multiple iterations of "re-explain Harper mechanics vs point at Harper docs").

1. Documentation-boundary rule

Harper maintains authoritative docs at docs.harperdb.io covering core, pro, and fabric. App/plugin/sample repos should:

• Document what's specific to the component (env var names, config shape, setup flow, integration API)
• Link to Harper docs for anything not component-specific (deployment mechanics, runtime env vars, Fabric config, core behavior, SQL, replication)

Re-explaining Harper mechanics in repo docs creates drift — Harper updates its docs, the repo's copy doesn't.

Applied in parallel:

• .github/review-scopes/harper/common.md — reviewer-facing: flag PRs that re-explain instead of link
• .github/workflows/claude-mention.yml + .github/workflows/claude-issue-to-pr.yml — author-facing: same principle for agents writing or revising docs

2. Capture .env-deploys-to-fabric fact

The last review round on #55 correctly flagged that a GitHub Actions env: block doesn't propagate to Fabric runtime, but left the path forward ambiguous because the actual mechanism (.env at app root is deployed alongside the component) wasn't in any layer. Adding it to harper/v5.md under Environment variables, plus a clarifying bullet on deploy credentials vs runtime secrets so future reviews don't re-derive the distinction.

Test plan

• YAML parses for both workflow files
• Dogfood: this PR's own review run applies the new common.md rule and picks up the .env-deploys-to-fabric context
• Follow-up: the documentation-boundary principle is worth proposing as a HarperFast/skills rule for customer-facing authoring guidance — I'll draft a separate PR for that after this lands.

🤖 Generated with Claude Code

[claude]

No blockers found.

What I traced

common.md — new Documentation boundary section

• Content is correct and consistent with how the rule is framed in v5.md
• The "borderline calls" nuance (short factual reminders OK, whole-section duplication not) is useful — it prevents the rule from becoming an overcorrection that kills useful context
• Placement at the end of the file is fine; it reads as additive to existing review checks

v5.md — .env deploy fact + deploy credentials vs runtime secrets distinction

• Verified against .harper-skills/harper-best-practices/rules/deploying-to-harper-fabric.md: the skill confirms CLI_TARGET* are loaded from .env via dotenv-cli before harperdb deploy_component . runs, and that CI deployments use GitHub secrets injected into the shell environment (not from .env). The deploy credentials vs runtime secrets distinction is accurate for the CI/CD case.
• The harperdb deploy_component . deploys the current directory as the component, making the ".env ships with the component" claim plausible. The skill doesn't state this explicitly, though — if you have a Harper docs URL that confirms it, linking it here would both satisfy the new common.md rule and make the claim verifiable for future readers without first-hand context. Not a blocker given the author's domain authority, just a maintainability note.
• The parenthetical "(Repo docs should still link to the Harper docs for the deployment mechanics...)" correctly scopes the linking obligation to user-facing docs rather than this reviewer-guidance file.

claude-issue-to-pr.yml / claude-mention.yml — Documentation scope boundary section

• Identical text added to both workflow agent prompts — symmetric application is correct
• Placement is well-chosen: after the Harper-specific paths guidance and before the commit/process sections in each file
• YAML multiline string indentation is consistent throughout; no parse concerns
• One minor asymmetry: the workflow prompt version ("LINK to the Harper docs rather than re-explaining") omits the "borderline calls" nuance from common.md. The workflows are guiding AI agents to default to linking, so being more conservative here is arguably right — but future-you may want to add a brief "short factual reminders are fine" caveat if agents start over-linking in practice.