Prove project recommendation value

PROJECT_STATUS.md

@@ -1,16 +1,17 @@
 # starboard — PROJECT STATUS
 
-Last updated: 2026-08-08
+Last updated: 2026-08-09
 
 ## Why/What
 
 Starboard is project-aware tool intelligence for GitHub: connect a public
 project, discover relevant open-source repositories with visible evidence, and
-keep a searchable personal library of starred repositories. The focused local
-implementation removes Fleet project coupling, Alerts, Reports, Stack Builder,
-standalone Radar, and weekly digest. Live remains
-[starboard.codevetter.com](https://starboard.codevetter.com); this local change
-has not been deployed.
+keep a searchable personal library of starred repositories. The focused product
+has removed Fleet project coupling, Alerts, Reports, Stack Builder, standalone
+Radar, and weekly digest. Live at
+[starboard.codevetter.com](https://starboard.codevetter.com), the current
+release adds public project preview, full-catalog hybrid retrieval, and a
+GitHub project picker.
 
 Out of scope: private repositories until the permission model is chosen,
 organization/team dashboards, non-GitHub providers, automated dependency
@@ -42,15 +43,19 @@ Star sync + public project connection ──► D1 (users, repos, user_repos, us
         ├── Full-text + facet search (GET /api/stars)
         ├── Semantic search: knowledgebase Worker; lexical-only when shared RAG is unavailable
         ├── Public catalog + repo_tools → Discover and Tool Intelligence
-        └── Connected project context → explained repository recommendations
+        └── Public preview or connected project context
+              → Vectorize + FTS + language candidates
+              → deterministic evidence reranking
+              → explained repository and tool recommendations
 ```
 
 **Embedding contract:** `EMBEDDING_DIM=768` in `src/lib/embeddings.ts` matches the `starboard-repos` Vectorize index. D1 stores only repository IDs and text hashes; dimension changes require a deliberate replacement index and re-embedding.
 
 **Data model highlights:** tags stored as JSON arrays on `user_repos`;
 `user_projects` connects a user to a shared public `repos` row; tool evidence
-lives in `repo_tools`; similar-project ranking uses visible language, topic,
-metadata, and tool matches with explicit fallback labeling. Additional tools
+lives in `repo_tools`; similar-project retrieval combines bounded Vectorize,
+full-catalog FTS, and language candidates before visible language, topic,
+metadata, and tool reranking with explicit fallback labeling. Additional tools
 are recommended only when detected in those grounded peers, with repository
 provenance. The workflow is free and has no billing or entitlement gate.
 
@@ -67,6 +72,15 @@ provenance. The workflow is free and has no billing or entitlement gate.
 
 ## Timeline
 
+- **2026-08-09 (project-value hardening released)** — Archived the
+  completed project-focus change after syncing its delta specs. Replaced the
+  500-most-starred recommendation pool with bounded hybrid candidate retrieval
+  across the eligible catalog, added a read-only public project preview and
+  on-demand GitHub public-repository picker, made login project-first, and
+  replaced digest-era analytics with identity-free recommendation evidence.
+  Tests, typecheck, lint, docs, strict OpenSpec validation, and the production
+  Cloudflare build pass.
+
 - **2026-08-08 (free project discovery shipped)** — Removed Alerts,
   Reports, Stack Builder, standalone Radar, weekly digest, and the checked-in
   Fleet project catalog. Added user-owned public GitHub project connections and
@@ -160,8 +174,8 @@ provenance. The workflow is free and has no billing or entitlement gate.
 | Foundation | GitHub OAuth (NextAuth v5), OpenNext Cloudflare deploy, core dashboard with sync, tags, collections, full-text search, virtual scroll |
 | Repo intelligence | Repo detail (`/explore`), comments/votes, public shared lists, legal/marketing shell |
 | Semantic search | knowledgebase Worker integration for relevance search; README-backed sync ingest; local embeddings retained for non-RAG Starboard features |
-| Connected projects (local, pending deploy) | Public GitHub project connections and evidence-based repository recommendations |
-| Discovery & tools | Public Discover, manually dispatched seed/enrich/embed, stored growth sorting, and Tool Intelligence |
+| Connected projects | Shipped public GitHub project connections, public preview, GitHub picker, and evidence-based repository and tool recommendations |
+| Discovery & tools | Public Discover, daily bounded seed/enrich/embed with manual dispatch, stored growth sorting, and Tool Intelligence |
 | Removed 2026-08-08 | Fleet project catalog, Alerts, Reports, Stack Builder, standalone Radar, weekly digest |
 | Ops hardening (2026-06-20) | `.env.example`, Vitest + Playwright path, pre-push lint, self-contained TypeScript/Astro landing for green CF builds |
 
@@ -170,11 +184,13 @@ provenance. The workflow is free and has no billing or entitlement gate.
 **Live:** [starboard.codevetter.com](https://starboard.codevetter.com)
 
 **Primary routes:** `/stars` (library) · `/explore/[...slug]` (repo detail) ·
-`/discover` · `/projects` · `/projects/[slug]` · `/lists/[slug]` · `/tools`
+`/discover` · `/project-preview` · `/projects` · `/projects/[slug]` ·
+`/lists/[slug]` · `/tools`
 
 **Primary API:** `/api/stars` · `/api/stars/sync` ·
-`/api/repos/[repoId]/*` · `/api/lists/*` · `/api/projects/*` · `/api/growth` ·
-`/api/tools` · `/api/embeddings/generate`
+`/api/repos/[repoId]/*` · `/api/lists/*` · `/api/project-preview` ·
+`/api/projects/*` · `/api/github/projects` · `/api/growth` · `/api/tools` ·
+`/api/embeddings/generate`
 
 | Surface | Role |
 |---------|------|
@@ -203,22 +219,25 @@ provenance. The workflow is free and has no billing or entitlement gate.
   so Workers AI, Vectorize, and D1 use native bindings without broad Vectorize
   credentials in GitHub.
 
-### Connected projects (implemented locally; not deployed)
+### Connected projects and public preview
+- Guests can preview a public GitHub repository without sign-in or a user-data
+  write, then carry the normalized repository through sign-in for explicit
+  connection.
 - Authenticated users can connect and disconnect public GitHub repositories
-  without a broader OAuth scope.
+  by URL or an on-demand public-repository picker without a broader OAuth scope.
 - `user_projects` isolates project connections per user while reusing shared
   repository metadata.
-- Deterministic recommendations explain language, topic, metadata, and tool
-  matches; sparse context is labeled as broad discovery.
+- Bounded Vectorize, full-catalog FTS, and language candidates feed deterministic
+  recommendations that explain language, topic, metadata, and tool matches;
+  sparse context is labeled as broad discovery.
 
 ### Discovery and intelligence surfaces
 - Public Discover page and `/api/discover` for the seeded popular repository
   corpus; authentication adds saved state and collection controls but is not
   required to browse, search, sort, filter, paginate, or open repo details.
 - Discover supports paginated 30-day growth ordering and detected-tool facets from indexed local snapshot/tool tables.
-- Manually dispatched GitHub Actions seed/enrich popular repos in D1 and embed
-  through native Worker bindings; automatic seeding remains paused pending an
-  explicit operating budget.
+- Daily bounded GitHub Actions seed/enrich popular repos in D1 and embed through
+  native Worker bindings; manual dispatch remains available for operator checks.
 - Star history and fastest-grower APIs/surfaces: `/api/repos/[repoId]/star-history`, `/api/growth`, Discover growth sorting, and repo-detail mini history from stored `repo_star_snapshots`.
 - Tool Intelligence: additive `repo_tools` index, `/api/tools`, `/api/repos/[repoId]/tools`, `/tools`, and `pnpm db:enrich-tools` for bounded SBOM/tree/manifest-based detection with source/confidence labels. Accuracy disclaimer is shown in-product because manifest/SBOM evidence is stronger than README/topic/metadata inference and C/C++ monorepos vary.
 - SaaS Maker feedback widget integrated; product analytics run directly through PostHog.

README.md

@@ -30,15 +30,18 @@ matches, and keeps personal stars searchable with tags and collections.
 
 ## Features
 
+- **Public Project Preview** — paste a public GitHub repository and inspect a
+  read-only recommendation sample before sign-in
 - **GitHub OAuth** — Sign in and sync your starred repos
 - **Smart Categories** — Auto-categorize repos (AI/ML, Frontend, DevOps, etc.)
 - **Custom Tags** — Create and assign colored tags to repos
 - **Collections** — Group repos into named collections
 - **Search** — Full-text search across name, description, and topics
 - **Filter** — By language, category, tag, or collection
 - **Sort** — Recently starred, most stars, recently updated, A-Z
-- **Projects** — connect public GitHub repositories for explained recommendations
-- **Similar Projects** — ground recommendations in comparable repositories
+- **Projects** — connect by URL or an on-demand public GitHub repository picker
+- **Similar Projects** — hybrid full-catalog candidates with deterministic,
+  visible-evidence reranking
 - **Grounded Tools** — see which tools peers use and the exact repository evidence
 - **Tool Intelligence** — inspect detected tools, confidence, and repository evidence
 - **Discover** — search and filter a seeded public repository catalog
@@ -89,6 +92,7 @@ AUTH_TRUST_HOST=true
 ```text
 src/app/stars/          main dashboard
 src/app/explore/        repo detail and discovery pages
+src/app/project-preview public read-only project intelligence
 src/app/projects/       connected GitHub projects and repository recommendations
 src/app/lists/          public shared list pages
 src/app/api/            auth, stars, lists, repo interactions
@@ -135,9 +139,12 @@ live in Vectorize.
 - GitHub star sync uses ETag caching to avoid unnecessary API calls.
 - GitHub star lists are scraped from GitHub HTML because there is no official API for that surface.
 - Projects are public GitHub repositories connected per user in D1. The current OAuth scope is not broadened for private access.
-- Similar projects use visible language, topic, metadata, and tool evidence;
-  grounded tool recommendations then name the exact peer repositories that use
-  each tool. Sparse results are labeled as broad discovery.
+- Similar projects combine bounded Vectorize, full-catalog FTS, and language
+  candidate lanes before visible language, topic, metadata, and tool reranking;
+  grounded tool recommendations then name the exact peers that use each tool.
+  Sparse results are labeled as broad discovery.
+- Product analytics use categorical recommendation and evidence buckets only;
+  repository identity and query text are excluded.
 - Filter and sort state lives in the URL through `nuqs`, so dashboard links are shareable.
 - Scheduled GitHub Actions seed and enrich popular repositories for discovery.
 - SaaS Maker supplies the feedback widget only; product analytics run directly through PostHog.

docs/architecture/data-flow.md

@@ -30,12 +30,16 @@ history and remains empty when insufficient samples exist.
 
 ```text
 public GitHub URL or owner/repository
-  → normalize and resolve through GitHub
+  → normalize and check the local catalog
+  → resolve one public GitHub repository on a catalog miss
+  → public preview: no user-owned write
+  → authenticated connection only after explicit confirmation
   → upsert shared repos row
   → insert user_projects ownership relation
   → load project metadata + repo_tools
-  → rank a bounded public-catalog candidate set
-  → return recommendations with evidence
+  → retrieve bounded Vectorize + full-catalog FTS + language candidates
+  → reciprocal-rank fusion + deterministic evidence reranking
+  → return recommendations, retrieval mode, and peer-grounded tools
 ```
 
 The route revalidates that the repository is publicly accessible. Project list,
@@ -46,5 +50,8 @@ project context produces an explicitly labeled broad-discovery fallback.
 
 Repository similarity remains a separate Vectorize path. D1 stores only
 `repo_embeddings(repo_id, text_hash)`; vector values live in the
-`starboard-repos` index. Similar-project recommendations currently use deterministic
-visible evidence so every reason can be explained.
+`starboard-repos` index. Project-aware recommendations use Vectorize as one
+candidate lane, then fuse it with full-catalog lexical and structured lanes.
+Deterministic visible evidence remains the final ranker so every reason can be
+explained. When semantic retrieval is unavailable, lexical and structured lanes
+remain usable; an all-lanes-empty state becomes an explicit broad fallback.

docs/operations/data-map.md

@@ -133,8 +133,9 @@ returns 503 and must not report global health. See
 ## Search activation evidence
 
 Privacy-safe aggregate activation counters are emitted to Foundry (PostHog)
-on successful search result inspection and saved/organized actions. No raw
-query text, repo IDs, repo full names, or user identifiers are sent. See
+on search and project recommendation views, inspections, feedback, and
+saved/organized actions. No raw query text, repo IDs, repo full names, or user
+identifiers are sent. See
 [`foundry.md`](foundry.md) for the sanitization contract and
 [`src/lib/analytics.ts`](../../src/lib/analytics.ts) `trackSearchOutcome`.
 

docs/operations/foundry.md

@@ -21,7 +21,11 @@ never sends:
 | --- | --- | --- |
 | `signup` | first session after account creation | `project_id` |
 | `activated` | first successful star sync | `project_id` |
-| `core_action` | each sync / list-created action | `project_id`, `action` (`repos_synced`/`list_created`) |
+| `core_action` | each sync, list-created, or project-connected action | `project_id`, `action` (`repos_synced`/`list_created`/`project_connected`) |
+| `project_connected` | a public project is durably connected | `project_id`, `source` (`manual`/`picker`) |
+| `recommendation_set_viewed` | project recommendations reach the user | `project_id`, `retrieval_mode`, `result_count_bucket`, `fallback` |
+| `recommendation_inspected` | a repository or tool recommendation is opened | `project_id`, `kind`, `rank_bucket`, `retrieval_mode` |
+| `recommendation_feedback` | useful/not-useful is selected | `project_id`, `kind`, `sentiment`, `rank_bucket`, `retrieval_mode`, `support_bucket`, `confidence_bucket` |
 | `returned` | return session by a user with prior activity | `project_id` |
 | `search_outcome` | every `/api/stars` search with a query | `project_id`, `surface` (`lexical`/`semantic`/`discover`), `result_count_bucket` (`zero`/`1-5`/`6-20`/`21+`) |
 | `result_inspection` | a user opens a repo detail from search results | `project_id`, `surface` (`repo_detail`) |
@@ -45,16 +49,17 @@ never sends:
 - The inactive historical `insight_reports` table is not an event source.
 - Foundry activation events carry **no** repo identity. The `search_outcome`
   event has only the surface and result-count bucket; `result_inspection`
-  has only the surface name.
+  has only the surface name. Project recommendation events use categorical
+  retrieval, rank, support, confidence, and sentiment buckets only.
 - The knowledgebase RAG index stores `full_name` in document metadata for
   result-to-repo mapping; this is the search backend (user-scoped via
   `user_id` in the index), not Foundry, and is not covered by this
   sanitization contract.
 
 ## Verification
 
-A future audit task (deferred — not blocking this capability) should grep
-all `track*` and `emit*` call sites to confirm no PII / query text / repo
-identity is passed. The current call sites are limited to
-[`src/lib/analytics.ts`](../../src/lib/analytics.ts) exports and
-[`src/app/api/stars/route.ts`](../../src/app/api/stars/route.ts).
+Audit `track*` and `emit*` call sites during analytics changes to confirm no PII,
+query text, or repository identity is passed. Current project event call sites
+live in the project connection API and the project recommendation components;
+their payloads are constrained by typed categorical helpers in
+[`src/lib/analytics.ts`](../../src/lib/analytics.ts).

docs/product/features.md

@@ -5,19 +5,25 @@ reasons, see [../architecture/decisions/](../architecture/decisions/).
 
 ## Project-aware discovery
 
+- Guests can preview a public GitHub repository before sign-in. Cataloged
+  repositories use stored evidence; uncataloged repositories use one public
+  GitHub metadata lookup. Preview creates no user-owned row.
 - Authenticated users can connect a public GitHub repository by URL or
-  `owner/repository` without broadening the current OAuth scope.
+  `owner/repository`, or choose from a bounded on-demand list of public GitHub
+  repositories, without broadening the current OAuth scope.
 - Connections are user-owned D1 relations; disconnecting a project does not
   delete shared repository metadata.
-- Projects receive deterministic similar-repository results from the seeded
-  public catalog using visible language, topic, metadata, and detected-tool
-  evidence.
+- Projects retrieve bounded Vectorize, full-catalog FTS, and language candidate
+  lanes before deterministic reranking with visible language, topic, metadata,
+  and detected-tool evidence.
 - Similar repositories ground tool recommendations. Each recommended tool
   lists the exact peer repositories and detection confidence that support it.
 - Recommendation cards state the matching evidence. Sparse-context results are
   explicitly labeled as broad discovery fallbacks and do not generate tool
   recommendations.
 - The complete workflow is free and has no billing or entitlement gate.
+- Recommendation views, inspections, and useful/not-useful feedback emit only
+  categorical buckets; repository identity and query text are excluded.
 
 ## Public discovery and tool intelligence
 
@@ -50,8 +56,8 @@ reasons, see [../architecture/decisions/](../architecture/decisions/).
 
 ## Catalog and operations
 
-- Manually dispatched seed, metadata-enrichment, tool-enrichment, and embedding
-  jobs with explicit per-run bounds.
+- Daily and manually dispatched seed, metadata-enrichment, tool-enrichment, and
+  embedding jobs with explicit per-run bounds.
 - Additive ordered D1 migrations; raw SQL with no ORM.
 - Vitest unit/integration coverage, Playwright path, Biome checks, docs
   validation, and OpenNext Cloudflare builds.

docs/product/overview.md

@@ -7,6 +7,8 @@ developer's public GitHub projects to a seeded open-source repository catalog,
 then explains which repositories and tools may fit the work being built.
 Similar repositories form the grounding layer: tool recommendations come only
 from normalized detections on those peers and name their repository sources.
+Guests can preview this value with a public repository before sign-in; a durable
+project connection remains an explicit authenticated action.
 
 The product also keeps a personal starred-repository library with search,
 lists, tags, saved state, and notes. Discover and Tool Intelligence remain
@@ -38,8 +40,9 @@ See [surfaces.md](surfaces.md) for the route and API map.
 
 ## Scope
 
-**In scope:** public repository discovery; evidence-aware tool intelligence;
-public GitHub project connections; project-aware repository recommendations;
+**In scope:** public repository discovery; public project preview;
+evidence-aware tool intelligence; public GitHub project connections;
+project-aware repository recommendations;
 starred-repository sync, organization, search, and public lists; repository
 details and stored star history.