docs: clarify env vars in quick start are for local dev; warn against .env for runtime secrets

[claude]

Summary

• Adds For **local development** label to the export command block in the Quick Start
• Adds a note explaining that Harper reads from the process environment directly (does not load .env automatically)
• Warns that Harper's .env convention is for dotenv-cli deploy CLI credentials, not runtime OAuth secrets
• Directs Harper Fabric users to inject secrets via CI/CD pipeline (e.g., GitHub repository secrets)

Closes #32

Test plan

• Doc-only change: npm run format:check passes for the changed file
• npm run lint reports no new errors

[claude]

Review: docs: clarify env vars in quick start

2 blockers found. Both are in the documentation itself — no code changes in this PR.

---

1. README.md — wrong deployment platform guidance

File: README.md:42
What: The new note recommends systemd unit file, Kubernetes secrets, and cloud provider secrets manager as the go-to production options.
Why it matters: Harper's default deployment target is Fabric. The review scope for this repo explicitly prohibits recommending generic non-Fabric patterns unless the user has opted out of Fabric. A developer reading this will reach for the wrong tooling. Ironically, docs/getting-started.md (same PR) gets the Fabric-first framing right — the README note should match it.
Suggested fix: See inline suggestion — replace the generic list with the same Fabric / CI/CD guidance used in getting-started.md.

---

2. docs/getting-started.md — .env advice is incorrect

File: docs/getting-started.md:35-36
What: The note tells users "Do not store OAuth secrets in a .env file" and implies .env is only for CLI_TARGET deploy credentials.
Why it matters: The standard npm create harper template scaffolds dotenv-cli into npm run dev (dotenv -- npm run dev:component). That script loads .env before the Harper runtime starts, making OAuth secrets placed there (OAUTH_GITHUB_CLIENT_ID, etc.) correctly available to the process — the exact same mechanism as CLI_TARGET. The distinction the note draws is artificial and contradicts the official Harper toolchain. A developer following the standard template will be told not to do the thing that actually works.
Suggested fix: See inline suggestion — explain that .env is fine for local dev (OAuth secrets included), warn only against committing it, then give the correct Fabric guidance for production.

---

Surfaces verified:

• README.md diff: new note at line 42 — fails Fabric-first check
• docs/getting-started.md diff: new note at lines 35–37 — incorrect .env restriction; Fabric guidance (line 37) is correct
• No code changes in this PR; architecture, security, and test layers not applicable

[heskew]

@claude address both blockers in claude[bot]'s review above. For README.md, mirror the Fabric/CI-secrets framing already in docs/getting-started.md. For docs/getting-started.md, loosen the .env restriction — .env via dotenv-cli is the correct local-dev pattern for OAuth secrets; only warn against committing it. Keep the Fabric production guidance.

[claude]

Review: PR #55 — docs: clarify env vars for local dev / Fabric

1. Fabric runtime secrets guidance conflates deploy credentials with runtime app configuration

Files: README.md:42, docs/getting-started.md:37

What: Both added notes tell Harper Fabric users to inject OAuth secrets (e.g. OAUTH_GITHUB_CLIENT_ID) via GitHub repository secrets passed through the CI/CD env: block in their deploy workflow.

Why it matters: The Harper v5 toolchain draws a hard line between two categories of secrets:

• Deploy credentials (CLI_TARGET, CLI_TARGET_USERNAME, CLI_TARGET_PASSWORD) — passed in the GitHub Actions env: block so the harperdb deploy_component CLI can authenticate with the cluster. The deploying-to-harper-fabric.md skill shows exactly this pattern.
• Runtime app configuration (OAuth client ID/secret) — described by the v5 conventions as "runtime configuration injected by the platform." This is a distinct mechanism; the platform (Fabric) is responsible for making these vars available to the running Harper component.

The env: block in a deploy workflow step scopes those vars to the npm run deploy process. There is no documented mechanism by which they become environment variables in the live Fabric environment where Harper actually processes OAuth requests. A user who follows the PR's guidance exactly could end up with correctly-deployed code that fails every OAuth flow at runtime because OAUTH_GITHUB_CLIENT_ID resolves to undefined.

Suggested fix: Determine how Fabric surfaces runtime app secrets to a deployed component (e.g., Fabric-level env var config, config.yaml interpolation with Fabric-managed secrets, etc.) and document that mechanism. If the CI/CD env: block pattern genuinely does propagate to the Fabric runtime (e.g., the deploy command persists them as cluster-level env vars), add a sentence making that explicit so users understand why the pattern works, not just that it works.

---

What the PR gets right

• Local-dev guidance (export + .env with dotenv-cli) aligns correctly with the authoritative creating-harper-apps.md and deploying-to-harper-fabric.md skills.
• "Don't commit it to source control" warning is appropriate and well-placed.
• Both files are consistent with each other.
• No code-path changes; purely additive doc clarification.

[heskew]

@claude please revise the two added notes to narrow their scope — this repo's docs shouldn't re-explain Harper/Fabric deployment mechanics, and in the current wording we're overreaching into territory that belongs in Harper's own docs.

Keep and preserve:

• The local-dev framing (export / .env + dotenv-cli — OAuth-specific because the env-var names are ours)
• The "don't commit .env to source control" warning

Change:

• Remove the specific "inject via GitHub repo secrets / CI/CD env: block" claim. That pattern is documented for deploy-CLI credentials (CLI_TARGET_*), but it's not the mechanism for runtime app secrets, and mixing the two in our docs misleads users.
• For production guidance, replace the current Fabric paragraph with a short pointer: something like "For Harper Fabric deployments, your app-root .env is deployed alongside your component, so the same .env you use locally works in production — see the Harper Fabric documentation for managing runtime environment variables at https://docs.harperdb.io/docs/fabric/managing-applications (or the current authoritative URL in the Harper docs)."

The goal is: this PR's docs stay OAuth-specific (which env vars to set, don't commit them). Anything about HOW Harper/Fabric loads env vars gets deferred to Harper's own documentation, for easier maintenance.

Scope this to README.md and docs/getting-started.md. Two-line commit, no other files.

[claude]

Done — pushed a two-line commit (68dc649) that:

• README.md: replaces the CI/CD injection sentence with a pointer to the Harper Fabric docs for managing runtime environment variables.
• docs/getting-started.md: same removal, replaced with the Fabric-specific note that the app-root .env is deployed alongside the component (so local and production use the same file), plus the docs link.

Local-dev framing and the "don't commit .env" warning are preserved as-is. No other files touched.

[claude]

Review: docs: clarify env vars in quick start (#55)

1. Incorrect Fabric guidance in docs/getting-started.md

File: docs/getting-started.md:37
What: The note states "your app-root .env is deployed alongside your component, so the same .env you use locally works in production." This is factually incorrect per Harper's Fabric deployment model.
Why it matters: Per the deploying-to-harper-fabric.md skill, .env in the Fabric context holds CLI deploy credentials (CLI_TARGET*) loaded by dotenv-cli — not runtime application secrets. The review scope for this repo explicitly states: "Runtime configuration is injected by the platform." Pointing users at .env as the production secret-management path for OAuth credentials directly contradicts the platform's actual mechanism and could lead integrators to either commit secrets to source control or be confused when CI/CD deployments (which start from a clean checkout) don't have the file. The note also contradicts itself: "just don't commit it to source control" and "the same .env you use locally works in production" can't both be true in a CI/CD pipeline.
Suggested fix: Match README.md, which handles this correctly by simply deferring: "For Harper Fabric deployments, runtime secrets are injected by the platform — see the Harper Fabric documentation for managing environment variables." (Inline suggestion posted.)

---

What I traced

• README.md change (line 42): correctly defers Fabric env-var mechanics to Fabric docs — no issue.
• docs/getting-started.md local-dev additions (lines 28, 35): correctly scoped to local dev, dotenv-cli note accurate — no issue.
• docs/getting-started.md Fabric note (lines 36–37): incorrect claim about .env deployment — blocker above.
• No code changes; no test, security, or API-contract surface to audit beyond the doc content.