Skip to content

block 7: OSS polish (README, CONTRIBUTING, SECURITY, quickstart, screenshots, badges, example config)#69

Merged
aksOps merged 7 commits intomainfrom
feat/block7-oss-polish
Apr 24, 2026
Merged

block 7: OSS polish (README, CONTRIBUTING, SECURITY, quickstart, screenshots, badges, example config)#69
aksOps merged 7 commits intomainfrom
feat/block7-oss-polish

Conversation

@aksOps
Copy link
Copy Markdown
Contributor

@aksOps aksOps commented Apr 24, 2026

Summary

Seven documentation-only commits completing Block 7 of the production-polish roadmap.

  • SECURITY.md (7.3): disclosure policy, 90-day embargo, per-severity fix SLA. Preserves the 72-hour ack commitment and 7-day remediation plan from the prior policy.
  • CONTRIBUTING.md (7.2): full Go+UI dev loop, CGO/sqlite_fts5 build tags, Conventional Commits style, pre-commit recipe. Preserves Windows-unsupported + sqlite-vec placeholder notes.
  • configs/docsiq.example.yaml (7.4): every v.SetDefault in internal/config/config.go has a matching comment-backed entry with default + env var. Legacy config.example.yaml now points at the new file.
  • docs/quickstart.md + docs/samples/ (7.5): 3-minute onboarding with a 3-document markdown corpus (Roman aqueducts, GraphRAG, Louvain) that indexes in <30s and produces a non-trivial entity graph.
  • docs/screenshots/ + ui/e2e + ui/scripts (7.6): five fresh @2x PNGs of Home/Notes/Documents/Graph/MCP captured against a live docsiq serve with seeded notes data. Reproducible via ui/e2e/screenshots.spec.ts + ui/scripts/optimize-screenshots.mjs. Each PNG compressed below the 500 KB per-image budget (largest: graph.png at 167 KB).
  • Badge row (7.7): CI, CodeQL, OpenSSF Best Practices, OpenSSF Scorecard, Go Report Card, License (MIT), Release, Go Version — every URL verified to return HTTP 200.
  • README refactor (7.1): three-command onboarding (install, index, query) on the first screen; Home + Graph screenshots inline; Community section links to CONTRIBUTING, SECURITY, COC, GOVERNANCE, CHANGELOG. Preserves architecture tree, UI/MCP/build/tests sections from the previous version.

Deviations from plan

  • The plan's install snippet used docsiq-linux-amd64 but actual release assets are versioned (docsiq-vX.Y.Z-linux-amd64), so the README install command was adjusted to resolve VERSION from the GitHub API before downloading.
  • Playwright spec needed three adjustments from the plan snippet: (a) __dirname via import.meta.url in ESM, (b) /docs instead of /documents (actual UI route), (c) /mcp reached via client-side router because the server claims /mcp for the MCP HTTP handler.
  • Coverage badge deferred — Codecov is not wired into CI. Tracked as a follow-up.

Test plan

  • Every badge URL returns HTTP 200 (8/8 verified via fetch)
  • Playwright spec runs cleanly against a live docsiq serve — 5/5 tests pass
  • node --check ui/scripts/optimize-screenshots.mjs passes
  • All five screenshots under 500 KB after sharp optimization
  • Every v.SetDefault(...) in internal/config/config.go has a matching key in configs/docsiq.example.yaml
  • Every internal link in the new README resolves (CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, GOVERNANCE, CHANGELOG, LICENSE, quickstart, example config, all five screenshots)
  • README install URL https://github.com/RandomCodeSpace/docsiq/releases/latest/download/docsiq-v0.0.3-linux-amd64 resolves with 302 to the CDN
  • 7 commits, one per task, each with the Co-Authored-By: Claude Opus 4.7 (1M context) trailer

🤖 Generated with Claude Code

aksOps and others added 7 commits April 24, 2026 02:00
…x SLA

Documents the preferred GitHub private advisory channel, the 90-day
coordinated-disclosure default, and per-severity fix targets. Preserves
the 72-hour ack commitment and 7-day remediation plan from the prior
policy. Establishes that only the latest tag and main HEAD receive
patches.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tyle guide

Covers both the Go (CGO + sqlite_fts5 tag) and UI (Vite + Vitest)
surfaces, the recommended pre-commit setup, and the Conventional Commits
format the project uses. Preserves the Windows-unsupported + sqlite-vec
placeholder notes from the previous version. Replaces the previous stub.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…rrides

Every ServerConfig, LLMConfig (Azure/OpenAI/Ollama), IndexingConfig,
and CommunityConfig field is present with its default and the
DOCSIQ_ env-var override. The old root-level config.example.yaml now
points at the new location.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/quickstart.md walks a new user from zero-install to first search
in five numbered steps. docs/samples/ ships a 3-document markdown
corpus (aqueducts, graphrag, louvain) that indexes in <30s and
produces a non-trivial entity graph for screenshots.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five fresh @2x PNGs of the embedded SPA against a fixture corpus
(notes written via PUT /api/projects/_default/notes for deterministic
graph data without an LLM). Reproducible via
ui/e2e/screenshots.spec.ts and ui/scripts/optimize-screenshots.mjs;
each output is compressed well below the 500 KB per-image budget.

The spec was adjusted from the plan snippet to: (a) use import.meta.url
for __dirname in ESM mode, (b) target /docs instead of /documents
(actual UI route), and (c) navigate to /mcp via client-side router
because /mcp is claimed by the server's MCP HTTP handler.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Extends the existing OpenSSF + Scorecard badge row with CodeQL
(running on every PR), an explicit MIT license badge, and a Go
Report Card link. Coverage badge deferred — Codecov is not yet wired
into the CI pipeline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Promotes a three-command onboarding block (install, index, query) to
the first screen, inlines Home/Graph screenshots, and links downstream
docs (quickstart, example config, CONTRIBUTING, SECURITY) into a
single Community section. No content lost — architecture, UI, MCP,
build, and tests sections are preserved.

Install snippet resolves the latest release tag dynamically because
the release assets are versioned (docsiq-vX.Y.Z-linux-amd64), so the
default /releases/latest/download/<name> URL would otherwise 404.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aksOps aksOps enabled auto-merge (squash) April 24, 2026 02:15
@aksOps aksOps merged commit 49dec02 into main Apr 24, 2026
11 of 12 checks passed
@aksOps aksOps deleted the feat/block7-oss-polish branch April 24, 2026 02:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant