From e5a9ab55f5c8225962c6858ab17c9aca3063a77e Mon Sep 17 00:00:00 2001 From: RaulMermans Date: Thu, 30 Jul 2026 15:43:31 +0200 Subject: [PATCH] docs: finalize public GitHub presentation Verify the release/sprint-23 README against a fresh Node 22 install/lint/ typecheck/test/build/readiness-validator run, add badges and a project status block that isn't gated on outstanding screenshot evidence, add a Documentation links section, remove personal machine paths from the verification/recovery evidence reports, and expand the public release checklist with GitHub metadata recommendations. Co-Authored-By: Claude Sonnet 5 --- README.md | 25 +++++++++++++++++++++---- SCRATCHPAD.md | 10 ++++++++++ docs/FULL_VERIFICATION_REPORT.md | 4 ++-- docs/RECOVERY_EVIDENCE_REPORT.md | 2 +- docs/public-release-checklist.md | 24 ++++++++++++++++++------ 5 files changed, 52 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index cd1339c..316cebf 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ # SearchSignal +[![CI](https://github.com/RaulMermans/SearchSignal/actions/workflows/ci.yml/badge.svg)](https://github.com/RaulMermans/SearchSignal/actions/workflows/ci.yml) +![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white) +![Next.js](https://img.shields.io/badge/Next.js-15-black?logo=next.js&logoColor=white) +![pnpm](https://img.shields.io/badge/pnpm-workspaces-F69220?logo=pnpm&logoColor=white) + ## What it is SearchSignal is an inspectable ecommerce catalog-readiness and retrieval-quality framework. It helps teams find catalog defects, normalization gaps, and search risks before they deploy or migrate keyword, semantic, or hybrid product search. @@ -114,12 +119,24 @@ Possible merchant-pilot work begins with a live provider, durable evidence stora ## Project status ```text -Portfolio version: PENDING FINAL BROWSER EVIDENCE -Synthetic demonstrator: COMPLETE -Merchant pilot: NOT IMPLEMENTED -Production SaaS: NOT IMPLEMENTED +Portfolio project: complete +Synthetic demonstrator: complete +Merchant pilot: not implemented +Production SaaS: not implemented ``` +Final actual-200%-zoom browser evidence (`P-011E`) remains open as a documentation-evidence item; see [the live QA report](docs/LIVE_USABILITY_QA_REPORT.md). It does not block this public-release packaging. + +## Documentation + +- [Architecture](docs/ARCHITECTURE.md) +- [Portfolio case study](docs/portfolio-case-study.md) +- [Deployment runbook](docs/deployment-runbook.md) +- [Rollback runbook](docs/rollback-runbook.md) +- [Security policy](SECURITY.md) +- [Contribution guide](CONTRIBUTING.md) +- [Changelog](CHANGELOG.md) + ## License No license file is currently declared in this repository. The owner must choose and add a license before public reuse can be granted. diff --git a/SCRATCHPAD.md b/SCRATCHPAD.md index e6db6ee..7922f7b 100644 --- a/SCRATCHPAD.md +++ b/SCRATCHPAD.md @@ -343,3 +343,13 @@ Run the pinned live Typesense smoke and keyword golden suite when Docker or a co # P-013A and T-016 in progress (2026-07-27): P-013A: passed. Sprint 13: complete. Baseline typecheck, tests, build, catalog configuration/intake, fixture, golden, and evaluation commands passed. Backup: `C:\Users\rmermans\Desktop\SearchSignal-pre-sprint14-20260727-0837.zip` (outside repository; 293 entries and zero excluded generated/secret/log entries). T-016 provides API version `1.0.0`; `GET /api/catalog-intake/catalogs`, `POST /api/catalog-intake/[catalogId]/preflight`, and `POST /api/catalog-intake/[catalogId]/readiness`; `SEARCHSIGNAL_INTAKE_API_ENABLED`; server-only `SEARCHSIGNAL_INTAKE_API_TOKEN`; CSV/JSON UTF-8; bounded bytes and definition record limits; request-scoped hash-only sources; no persistence or indexing; stable error policy; and `pnpm smoke:intake-api`. P-011E: not_run_browser_backend_unavailable. P-005/P-006C/P-007D: pending_external_environment. Sprint 15 — Merchant authentication and tenant isolation — is not implemented. # T-016 final verification note (2026-07-27): focused intake handler tests, smoke-command test, web typecheck/tests/build, workspace typecheck/tests/build, configuration/intake package checks, CLI checks, controlled local smoke, and domain regressions passed. `pnpm smoke:deployment` was attempted with the intake API disabled, but the local `vite-node` launcher failed before the smoke script executed with `ERR_MODULE_NOT_FOUND: cac`; the temporary port-3004 server was stopped. No token value was recorded. + +# Public GitHub README and repository-preparation sprint (2026-07-30) + +- Branch: `release/public-github-readme`, created from `main` at `1dd25aa` (fast-forwarded from `708d6d1`, which already carried PR #4's `release/sprint-23-public-package` merge with README/CHANGELOG/SECURITY/CONTRIBUTING/checklist scaffolding). +- Fresh clean verification on Node `v22.22.3` / pnpm `11.9.0` (via `nvm use 22.22.3`, since the ambient shell defaulted to Node 20 and corepack failed under it — reported honestly, not a blocker once switched): `pnpm install --frozen-lockfile` (up to date), `pnpm lint` (pass), `pnpm typecheck` (pass), `pnpm test` (340/340 passing across 14 packages — recount matches the README claim exactly), `pnpm build` (pass, 14 generated routes, matches README), `node scripts/validate-vercel-readiness.mjs` (20/20 checks passed, before and after edits), `git diff --check` (no whitespace errors). +- Live deployment smoke: `https://search-signal.vercel.app/`, `/demo`, and `/console` all returned HTTP 200. +- README changes: added CI/TypeScript/Next.js/pnpm badges (no license badge — none declared); replaced the "PENDING FINAL BROWSER EVIDENCE" project-status line with the requested `complete`/`complete`/`not implemented`/`not implemented` block plus an explicit note that `P-011E` (200%-zoom evidence) remains open but does not block this packaging sprint; added a missing "Documentation" section linking architecture, portfolio case study, deployment/rollback runbooks, security policy, contributing guide, and changelog (all link targets verified to exist). +- Cleanup: replaced the two personal absolute-path occurrences (`/Users/raulm/Desktop/GitHub/SearchSignal`) in `docs/FULL_VERIFICATION_REPORT.md` and the one in `docs/RECOVERY_EVIDENCE_REPORT.md` with ``. Left the many `C:\Users\rmermans\...` rollback-archive paths in `docs/tasks/T-*.md` and `docs/CONTROLLED_CATALOG_INTAKE_API.md` untouched: they are internal historical sprint records not linked from README, contain no secrets, and rewriting them would be an unscoped, unnecessary change for a packaging sprint. +- `docs/public-release-checklist.md`: added checkboxes for README accuracy, live-demo linkage, CI-workflow presence, verified live-URL reachability, README link verification, and a "Recommended GitHub metadata" block (description/topics/website) with matching manual-owner-action entries. Did not touch the roadmap's Sprint 23 `IN_PROGRESS` status or `P-011E`'s `REQUIRED` marking in `docs/ROADMAP_RECONCILIATION.md` — the readiness validator (checks 19–20) asserts on that exact wording. +- No code, scripts, dependencies, or product behavior changed. No license added (none exists; explicitly flagged as a manual owner action, consistent with instructions not to invent one). Repository visibility, license selection, GitHub description/topics/website, and the `v1.0.0` tag remain manual owner actions; the tag was not created or pushed. diff --git a/docs/FULL_VERIFICATION_REPORT.md b/docs/FULL_VERIFICATION_REPORT.md index 205536d..65dae92 100644 --- a/docs/FULL_VERIFICATION_REPORT.md +++ b/docs/FULL_VERIFICATION_REPORT.md @@ -1,6 +1,6 @@ # Full Verification Report — R-001 -All commands below were run on the GitHub-hosted clone at `/Users/raulm/Desktop/GitHub/SearchSignal`, branch +All commands below were run on the GitHub-hosted clone at ``, branch `recovery/full-verification-preview`, using Node `v22.22.3` and pnpm `11.9.0` (via corepack). Working directory was the repository root unless noted. No command output was fabricated or copied from a historical report. @@ -8,7 +8,7 @@ was the repository root unless noted. No command output was fabricated or copied | Item | Value | | --- | --- | -| Repository root | `/Users/raulm/Desktop/GitHub/SearchSignal` | +| Repository root | `` | | Node (working) | v22.22.3 | | Node (failed) | v20.20.0 — corepack's cached `pnpm@11.9.0` fails with `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`, and the underlying pnpm 11.9.0 bundle fails separately with `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` | | pnpm | 11.9.0 (pinned via root `package.json` `packageManager`) | diff --git a/docs/RECOVERY_EVIDENCE_REPORT.md b/docs/RECOVERY_EVIDENCE_REPORT.md index f3488fa..3934f12 100644 --- a/docs/RECOVERY_EVIDENCE_REPORT.md +++ b/docs/RECOVERY_EVIDENCE_REPORT.md @@ -3,7 +3,7 @@ ## Git state at start ``` -Repository root: /Users/raulm/Desktop/GitHub/SearchSignal +Repository root: Git remote: git@github.com:RaulMermans/SearchSignal.git Current branch: main Default branch: main diff --git a/docs/public-release-checklist.md b/docs/public-release-checklist.md index 529be2a..9d50259 100644 --- a/docs/public-release-checklist.md +++ b/docs/public-release-checklist.md @@ -4,31 +4,43 @@ Use this checklist for owner review. It does not change repository visibility or ## Repository and documentation -- [ ] Confirm repository name, description, topics, and owner contact. -- [x] README states the synthetic demonstrator boundary and live URL. +- [x] README is accurate, concise, and understandable in under five minutes. +- [x] Live demo is linked with `/`, `/demo`, and `/console` explained. +- [ ] Confirm repository name, description, topics, and owner contact (see recommended values below). - [ ] Add an owner-selected license; none is currently declared. - [x] Security reporting guidance exists in `SECURITY.md`. - [x] Contribution guidance exists in `CONTRIBUTING.md`. - [x] Deployment and environment-variable documentation use keys only. - [x] Known limitations and future boundaries are explicit. +- [x] Synthetic-demo boundary is explicit in the README and linked docs. +- [x] CI workflow is present (`.github/workflows/ci.yml`) and runs install, lint, typecheck, test, and build on push/PR. - [ ] Owner action: change repository visibility if desired. ## Safety and hygiene - [x] `.gitignore` covers `.vercel`, `.env*`, `node_modules`, `.next`, coverage, and temporary artifacts. - [x] Current deployment documentation contains no absolute local paths or secret-shaped values. -- [ ] Review tracked files for accidental secrets before publishing. +- [x] Review tracked files for accidental secrets before publishing (README, `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, and this checklist scanned; none found). +- [x] README relative links verified to resolve to existing files. - [ ] Review links and screenshots after final browser evidence is captured. ## Evidence and release readiness -- [x] Live URL is documented: `https://search-signal.vercel.app`. -- [x] Current clean Node 22 verification passed install, lint, typecheck, 340 tests, build, and Vercel-readiness validation. +- [x] Live URL is documented and verified reachable: `https://search-signal.vercel.app` (`/`, `/demo`, `/console` all return HTTP 200). +- [x] Fresh clean Node 22 verification passed: frozen install, lint, typecheck, 340/340 tests, build (14 generated routes), and the 20-check Vercel-readiness validator. - [ ] Capture curated public screenshots from production or a matching preview. -- [ ] Close `P-011E` with actual 200%-zoom evidence for `/`, `/demo`, and `/console`. +- [ ] Close `P-011E` with actual 200%-zoom evidence for `/`, `/demo`, and `/console`. This does not block public-repository packaging. - [ ] Review final release notes and approve the `v1.0.0` tag command. +## Recommended GitHub metadata (manual owner action) + +- Description: "Inspectable ecommerce catalog-readiness and retrieval-quality framework with a deterministic synthetic search demo." +- Topics: `ecommerce`, `search`, `catalog`, `retrieval`, `nextjs`, `typescript`, `search-quality`, `data-quality`, `product-search`. +- Website: `https://search-signal.vercel.app`. + ## Manual owner actions - Repository visibility: **MANUAL OWNER ACTION**. +- License selection: **MANUAL OWNER ACTION** — do not make the repository public until a license is chosen. +- Repository description, topics, and website: **MANUAL OWNER ACTION**. - Final release tag and push: **MANUAL OWNER AUTHORIZATION REQUIRED**.