Plan a public-facing Arq surface (arq-docs) without exposing proprietary logic

[fheikens]

Context

The flagship product Arq is private, so a GitHub visitor sees only two supporting tools and none of the product the company sells. The website describes Arq Analyzer / Workbench / Insight, but there is no public artifact, docs, or demo to back it. This is the single biggest "early/solo project vs venture-scale company" gap on GitHub — and it is closable without open-sourcing the engine.

This is a planning/umbrella issue. Output is a plan, not yet an implementation.

Acceptance criteria (plan deliverable)

• Decide the public surface: a arq repo stub vs a dedicated arq-docs repo. Recommend arq-docs (public) to avoid an empty-looking flagship repo.
• Define contents that expose zero proprietary logic: product overview, high-level architecture diagram (collector -> analyzer -> workbench, boundaries only), screenshots of Arq Workbench, a canned/sample diagnostic output ("signals -> triage ticket"), security model summary, links to docs/pricing.
• Define a runnable or canned demo path building on Arq-Signals' existing snapshot-example/ (signals in -> sample Arq output) with no live engine exposure.
• Explicit review checklist to ensure no detection-rule internals, prompts, or proprietary heuristics are published.
• Sub-issues filed per the issue-first workflow once the plan is approved (effort moves to children).

Change type

Planning -> later documentation + a new public repo. No code in this issue.

[fheikens]

Plan: public-facing Arq surface

Planning deliverable for this issue. No repo or content is created until this plan is approved. Everything proposed below is already public on elevarq.com or in the open Arq-Signals repo — nothing here exposes engine internals.

1. Surface decision

Recommendation: a new public repo Elevarq/arq-docs.

• A public arq is impossible: the private flagship already owns the Arq name (case-insensitive collision in the org). So the canonical-namespace option is off the table regardless.
• arq-docs avoids an empty-looking flagship repo and reads as an intentional docs/demo surface for a commercial product.
• The repo's README.md becomes the thing a GitHub visitor sees when they go looking for the product, closing the "flagship is a 404" gap from the review.
• Source of truth stays the website (elevarq.com/docs); arq-docs mirrors/links the public-facing material and hosts the GitHub-native demo. We avoid doc drift by keeping arq-docs thin and link-heavy rather than duplicating the site.

Alternative considered: docs only on the website, no GitHub repo. Rejected — it leaves the GitHub presence gap the external review flagged as the single biggest issue.

2. Contents (zero proprietary logic)

All drawn from currently-public material:

• README — what Arq is ("PostgreSQL intelligence platform: continuous detection, root-cause diagnosis, resolution guidance"), the open-core relationship to Arq-Signals, and the collect → diagnose → review → ticket flow. Links to website docs, pricing, contact.
• Architecture overview — the three-component model only, at the boundary level: Arq Signals (open collector) → Arq Analyzer (deterministic detection rules + Arq Insight bounded, evidence-cited LLM explanations) → Arq Workbench (operator UI; tickets to GitHub/Jira). A simple box diagram of data flow. No rule logic, no thresholds, no prompts, no scoring.
• The finding model — the public 9-field structure (severity, confidence, problem statement, why it matters, cited evidence/metrics, recommended action with SQL). This is the shape of output, not how it's derived.
• Deployment & security model — runs in your infrastructure, read-only credentials over the standard protocol, no agents/schema changes/sidecars, query text and result data never leave your network. Reuse the restrained, readiness-language posture from Elevarq/.github SECURITY-POSTURE.md.
• Screenshots — Arq Workbench UI (none are public yet → a sub-issue to capture sanitized screenshots with synthetic data only).
• A sample finding — one realistic, fully synthetic finding rendered in the 9-field shape.

3. Demo path (canned, no live engine)

Build directly on Arq-Signals' existing examples/snapshot-example/:

• Take the existing public sample snapshot (signals in).
• Add a canned, hand-authored sample Arq output (a small set of findings in the 9-field shape) as static fixture files — not produced by the real Analyzer, clearly labelled as an illustrative sample.
• A short walkthrough: "here is a snapshot Arq-Signals produces; here is the kind of triage Arq generates from it."
• No Analyzer/Workbench code, no live engine, no real detection output. The demo shows the input→output shape, nothing about the derivation.

4. Proprietary-boundary review checklist (applied before publish)

• No detection-rule logic, thresholds, or rule names beyond the public examples (vacuum lag, index bloat, query regression, WAL retention).
• No LLM prompts, prompt structure, or Insight grounding mechanics.
• No scoring/confidence formulas or heuristics.
• No source code, internal module names, or repo-split/workspace internals.
• All sample data synthetic; no real customer data, hostnames, or credentials.
• Screenshots scrubbed of internal URLs, identifiers, and non-public features.
• Every claim matches something already public on elevarq.com (no new commitments).
• Security/compliance wording stays in readiness language ("designed for", "aligned with"); no certification claims.

5. Proposed sub-issues (effort moves here on approval)

1. Create Elevarq/arq-docs repo + README (overview, open-core, flow, links) — effort:S, priority:P1.
2. Architecture overview + data-flow diagram (boundary-level) — effort:S.
3. Finding model + synthetic sample finding — effort:XS.
4. Deployment & security model page (reuse SECURITY-POSTURE language) — effort:XS.
5. Sanitized Workbench screenshots (synthetic data) — effort:S, depends on screenshot capture.
6. Canned demo built on Arq-Signals snapshot-example/ — effort:M.
7. Cross-link: org profile README "Commercial" entry → arq-docs; website → repo — effort:XS.

This parent issue becomes a tracking issue once the sub-issues are filed (its effort label moves to the children).

Open questions for approval

1. arq-docs repo, as recommended? (vs website-only)
2. OK to reference the three components by name publicly? (all already on elevarq.com — confirming, since this issue is about not over-exposing.)
3. Are sanitized Workbench screenshots available / can they be produced with synthetic data, or defer that sub-issue?

[fheikens]

⚠ Patent guardrail (added per maintainer instruction)

A patent is still to be filed. The public Arq surface must not disclose anything patent-sensitive yet. This tightens the proprietary-boundary checklist:

• Nothing about detection/diagnosis techniques or mechanisms — including anything related to spoofing or how findings are derived.
• Do not go deep. Stay at or below the depth already published on elevarq.com. If something is not already on the public website, it does not go in arq-docs yet.
• No data-flow internals, no "how it works", no sequence/mechanism diagrams — naming the three components (already public) is the ceiling, not a flow of how they transform data.
• When in doubt, leave it out and ask.

Re-categorized sub-issues

Safe now (shallow, website-mirrored only):

• arq-docs: create repo + README #14 README — what Arq is + open-core link + the public collect → diagnose → review → ticket framing, links to the site. No mechanism.
• arq-docs: deployment + security model page #17 deployment/security model — already-public posture only.

Deferred until the patent is filed (or reviewed by maintainer):

• arq-docs: architecture overview + data-flow diagram #15 architecture data-flow diagram — defer the diagram and any flow-of-how; a plain named-component list is the most that ships now.
• arq-docs: finding model + synthetic sample finding #16 finding model — the 9-field output shape is public, but holding until reviewed to be sure it reveals nothing about derivation.
• arq-docs: canned demo built on Arq-Signals snapshot-example #19 canned demo (signals → findings) — deferred, this most directly shows the diagnostic transformation.

Building paused on the deferred items. Proceeding (pending maintainer confirmation) only with the shallow, website-mirrored README and security page.

[fheikens]

On hold per maintainer — the public Arq surface is deferred (we'll do this later). Plan and sub-issues (#14-#20) are filed with the patent guardrail recorded above. No arq-docs repo or docs were created. Resume only when the patent is filed / maintainer gives the go-ahead.