This page is the shortest truthful answer to:
We keep three separate public ledgers: the release ledger (linked to the latest GitHub release), the remote main ledger (the current head and its workflow/read-back receipts), and the distribution ledger (external registry or marketplace proof). Each claim in this doc points to one of those ledgers so readers can verify release vs remote vs distribution truth without chasing internal blueprints or archive mess.
Use it like a status board, not like a sales page.
If you need the volatile internal execution ledgers instead of the short public board, use the maintainer-only planning ledger. Public docs intentionally keep only the stable operator-facing summary here.
Release-current truth is a separate ledger from current remote main.
Always verify the latest live tag together with the current remote head before
repeating any “release-aligned” claim, because docs/governance closeout commits
can move main forward again after a release is cut.
SourceHarbor is already a real, source-first product-shaped repository.
It has:
bin/* entrypointsWhat it does not have today:
Treat release-current truth as its own ledger.
Current live reading:
main head before any release-aligned claim is repeatedPractical implication:
main
headmain moves ahead again
after the tag cut or after a docs/metadata sync mergemain moves again after this point, re-check whether release-current truth
still matches the remote head before repeating release-aligned claimsThe public repo now has strong current-main proof, but release-current truth
and official-surface distribution truth are still separate ledgers.
main is active and externally verifiable through GitHub checks and
workflow-dispatch lanes when those current-head runs have been freshly rereadbuild-public-api-imagebuild-ci-standard-imagerelease-evidence-attestmain, so the front
door, subscriptions atlas, feed desk, and reader detail surfaces should be
read as current-main truth rather than repo-local archive-only workUse:
These are the strongest current claims:
./bin/bootstrap-full-stack, ./bin/full-stack up, ./bin/doctor, and the runtime route snapshot under .runtime-cache/run/full-stack/resolved.env./bin/full-stack up can now attempt the repo-owned core_services.sh up path when Temporal is down before it gives up on worker readinessbin/* entrypoints remain the repo-local command truth, while packages/sourceharbor-cli adds a thin installable bridge for public discovery and starter flowspackages/sourceharbor-sdk now exposes a thin contract-first SDK over the same HTTP contract and shared route semanticsstarter-packs/ is the public entry directory, while docs/public-skills.md, docs/compat/*, templates/public-skills/*, and examples/* act as companion first-cut starter assets without exposing internal .agents/skills/subscriptions front door now consuming the same template catalog exposed through API and MCP while also accepting one-off video/article URLs into the today lanemode=full run can complete again after the Gemini fast-model rename, upload-wait hardening, and lightweight proxy-video path landed in the worker/runtime layerClusterVerdictManifest, PublishedReaderDocument, CoverageLedger, TraceabilityPack, repair modes, and NavigationBrief now exist as repo-side runtime surfaces over ConsumptionBatch/feed remains the digest/job reading lane, but digest items can now surface the current published reader document route when a current reader edition already exists for that source item/reader, /search, /ask (story-aware, briefing-backed answer/change/evidence flow with truthful raw-retrieval fallback, selected-story drill-down, and a server-owned story page payload that now reuses one canonical selected-story object from Briefings), /briefings (server-owned briefing page payload for selected story, compare route, and Ask handoff), /mcp, /ops, /subscriptions/watchlists, /trends (merged stories + recent evidence), /briefings (summary -> differences -> evidence for one watchlist, now with one shared selected-story payload that carries forward into Ask), /playground, and GET /api/v1/jobs/{job_id}/bundle/api/v1/reader/* plus reader MCP tools for document listing, detail, and navigation briefThese are the strongest outward-facing artifacts that already exist today:
config/public/github-profile.jsondocs/assets/sourceharbor-social-preview.pngWhat is still missing for a stronger public-ready claim:
For the exact package, registry, and listing ledger, stop here and use public-distribution.md. This page only keeps the short public-face summary plus blocker families.
These surfaces are real, but their strongest proof still depends on external conditions:
| Surface | Current truth | Gate |
|---|---|---|
| Notifications / reports | implemented routes and settings exist | verified sender configuration, especially RESEND_FROM_EMAIL, plus a target mailbox |
| UI audit Gemini review | base audit is real and a recent maintainer-local proof pass exercised the Gemini review layer | other environments still need Gemini access if they want the review layer |
| Computer use | contract and service exist, and a recent maintainer-local proof pass reached the provider | valid Gemini access, supported account capability, and a real screenshot/input contract |
| Long live smoke | repo path exists, the repo-managed bootstrap -> up -> status -> doctor path was re-proven again, and the default strict smoke can now prove the core live product path without pretending sender identity or the optional reader stack is already configured |
the notification/provider sub-lane still depends on operator-managed sender identity, especially RESEND_FROM_EMAIL; the reader stack still requires explicit Miniflux/Nextflux enablement when you want that extra lane checked |
These are the durable site-level capability boundaries worth remembering.
| Site | Current repo role | Strongest layer today | Gate / boundary | Verdict |
|---|---|---|---|---|
| Google Account | local browser-proof anchor for login persistence and repo-owned Chrome sanity checks | DOM / page-state proof only | local login state when you intentionally run real-profile proof | already-covered |
| YouTube | strong-supported source plus local live browser proof target | hybrid: Data API + DOM / page-state proof | shared operator key persistence and local login state when strict live proof is reopened | already-covered |
| Bilibili account center | local account-proof anchor for the strong-supported Bilibili source lane | DOM today, hybrid later if stronger account-side automation is justified | human login in the repo-owned Chrome profile | external-blocked |
| Resend dashboard | operator-side notification and sender-identity proof surface, not a content-ingestion source | admin UI + provider configuration | human login plus RESEND_FROM_EMAIL / sender-domain setup |
external-blocked |
| RSSHub / RSS sources | generalized source-universe intake substrate | HTTP / API, not browser-first | source availability and route/feed correctness, not browser login | already-covered |
If you want the more exact “what can still be deepened safely” ledger, read site-capability.md.
These are intentionally not live hosted proof:
/playgroundSafe interpretation:
Two directions remain explicitly in the bet bucket:
| Direction | Current decision |
|---|---|
| Agent Autopilot / advanced agent workflows | human-in-the-loop spike is worth considering; product claim is not |
| Hosted / managed workspace | no-go for current positioning; only a small hosted-shaped evaluation slice is worth reconsidering later |
Read the stable public boundaries:
This is the short scoreboard for the directions most likely to get overstated.
| Track | Current bucket | Why now |
|---|---|---|
| Codex / GitHub Copilot / Claude Code / VS Code agent workflows via MCP + HTTP API | ship-now | the repo already has real MCP, API, search, ask, and job-trace surfaces |
| Repo-local CLI/help facade | ship-now | ./bin/sourceharbor is already a truthful discoverability layer over bin/* |
| Packaged public CLI bridge | ship-now | packages/sourceharbor-cli is now the installable public bridge, while the fuller repo-local operator CLI remains ./bin/sourceharbor |
| Public TypeScript SDK | ship-now | packages/sourceharbor-sdk now exposes the contract-first builder layer over the existing HTTP contract |
| Codex-compatible plugin bundle | ship-now | starter-packs/codex/sourceharbor-codex-plugin/ is now the strongest public Codex bundle the repo can ship before official self-serve listing exists |
| GitHub Copilot plugin bundle | ship-now | starter-packs/github-copilot/sourceharbor-github-copilot-plugin/ now gives GitHub Copilot a real source-installable plugin bundle over the same MCP/API truth |
| Claude Code plugin bundle | ship-now | starter-packs/claude-code/sourceharbor-claude-plugin/ is now the strongest public submission-ready bundle for Claude Code |
| VS Code agent plugin bundle | ship-now | starter-packs/vscode-agent/sourceharbor-vscode-agent-plugin/ now gives VS Code agent workflows a real source-installable plugin bundle over the same MCP/API truth |
| OpenClaw via local starter pack + MCP / HTTP substrate | first-cut | the repo ships a compatibility page plus a first-cut local OpenClaw starter pack, but it still is not a marketplace or primary front-door claim |
| OpenClaw ClawHub package template | first-cut | the repo ships a publish-ready metadata template, but there is still no live ClawHub publish receipt and CLAWHUB_TOKEN is currently unset locally |
| Official MCP Registry listing + metadata template | ship-now | a fresh anonymous registry read-back confirms an active SourceHarbor MCP entry; exact public version drift now lives in public-distribution.md, while the durable truth here is that listing existence is proven and newer refresh first depends on PyPI serving sourceharbor==0.1.19 before registry-side publish auth matters |
| PyPI package surface | ship-now | the public sourceharbor project is live; exact public version drift now lives in public-distribution.md, while the durable truth here is that refresh is blocked by a PyPI Trusted Publisher mismatch surfaced as invalid-publisher, not by package absence |
| Site-specific MCP directory listing inputs | first-cut | config/public/mcp-directory-profile.json plus the public distribution ledger give the repo a real per-directory listing packet baseline, but same-day submit/read-back still varies per site |
| Public Python SDK | later | no public package surface exists yet |
| Public skills pack / templates | first-cut | docs/public-skills.md, docs/compat/*, templates/public-skills/*, and examples/* now provide a usable first public starter surface, but not a fully hardened ecosystem product yet |
| Plugin / extension marketplace as the primary product identity | no-go now | plugin-first positioning would still overstate the current repo truth even after the new bundle/template surfaces landed |
| Agent Autopilot (approval-first research ops) | spike-only | only the approval-first research-ops slice is worth reopening |
| Full autonomous autopilot | no-go now | approval, rollback, identity, and provider readiness are not strong enough |
| Thin managed evaluation slice | later | only a narrow managed bridge is worth reconsidering after current proof boundaries stay intact |
| Full hosted workspace | no-go now | multi-tenant auth, custody, isolation, and support contracts are not ready |
| Growth / moat thesis | ship-now | the current moat is the proof-first control tower story plus reusable compounder surfaces, not hosted scale or plugin sprawl |
These are the genuine external or human-only dependencies still left after the current maintainer re-audit:
RESEND_FROM_EMAIL, a verified sender/domain, and a destination mailboxRaw non-empty values for YOUTUBE_API_KEY, RESEND_API_KEY, and
GEMINI_API_KEY are no longer the main blocker story. The remaining blockers
are more specific than generic “secret missing” language.
| Blocker | Freshly verified state | Why this is external/human-only | Exact action |
|---|---|---|---|
| Resend sender identity | provider canary still reports config_error; sender configuration remains incomplete because RESEND_FROM_EMAIL is still missing |
repo code already exposes notifications and settings; GitHub/release truth is no longer the missing piece | set RESEND_FROM_EMAIL, verify the sender/domain in Resend, choose a real destination mailbox, then rerun the provider canary or strict live-smoke lane |
| YouTube strict live-smoke | recent local proof now passes direct probe, provider canary, and strict live-smoke preflight; the remaining step is restoring operator-managed YouTube API access whenever the full live lane is reopened | repo-side implementation is no longer the blocker; the remaining action is making the intended YouTube API access available when the lane is rerun | restore the intended YouTube API access in the environment used for the live-smoke lane, then rerun the strict live-smoke lane when you want the full end-to-end receipt |
| PyPI version refresh | public-distribution.md is the canonical place for the exact live version read-backs and publish-state gap | the latest live PyPI read-back still serves sourceharbor==0.1.14, while the repo package line is 0.1.19; the latest publish attempt reached the real publish step and failed with exact blocker invalid-publisher |
configure the PyPI Trusted Publisher for repository xiaojiou176-open/SourceHarbor, workflow .github/workflows/publish-pypi.yml, and environment external-pypi-publish; then rerun publish-pypi.yml and read the live version back before repeating a newer claim |
| Official MCP Registry version refresh | public-distribution.md is the canonical place for the exact live registry read-back and current refresh gap | the public registry entry still reads 0.1.14; the latest refresh attempt failed early because the workflow first verifies that live PyPI already serves sourceharbor==0.1.19, and today that prerequisite still fails |
after PyPI serves 0.1.19, rerun publish-mcp-registry.yml and read the refreshed registry entry back before repeating a newer snapshot claim |
| MCP.so direct listing | public-distribution.md now holds the exact current direct-page read-back and listing status | the repo-side packet exists, but this public route still does not prove a live listing | capture either a real submit/accept receipt or a later direct-page read-back in public-distribution.md that shows the listing has appeared |
| mcpservers.org listing | public-distribution.md now holds the exact current direct/search read-back and listing status | the repo-side packet exists, but the public surface still does not show a readable listing proof | capture either the approval/listing URL or a later public read-back in public-distribution.md that shows the server |
| awesome-opencode maintainer review | public-distribution.md now holds the current upstream PR state | the repo-side packet already landed upstream, so the remaining step is maintainer review rather than repo work | wait for merge/rejection/feedback and capture the resulting URL or maintainer comment in public-distribution.md |
| GitHub social preview | the tracked asset already exists in-repo, but live upload/read-back still remains a manual GitHub Settings step | the remaining step is a manual upload in GitHub repo settings, not a repo-code change | open Settings -> General -> Social preview, upload docs/assets/sourceharbor-social-preview.png, then read the live setting back |
Fresh GitHub-side verification must be rerun against the current remote head
whenever main moves again. The safe reading rules are:
main, latest release, and workflow-dispatch evidence as separate ledgersheadSha still matches the current remote headmain, because post-release docs/governance closeouts can move main ahead again before the next tag is cutconfig/public/github-profile.json before repeating the claim