docs: tester quickstart + README front door under one story (D1) - #345
Merged
Conversation
… with control + proof There was no single first-run page: README offered three lanes plus a native escape hatch, GettingStarted a fourth ordering, DocsIndex sixteen "start here" items with RELEASE.md at #3, and none of them reached the trust loop. The first command in README (`dotnet build ... --no-restore`) fails on a fresh clone with NETSDK1004. Four product stories coexisted (local-first AI runtime / "autopilot panel", audited copilot + Cloud SKU, autonomous capability extension, certified artifacts). docs/TesterQuickstart.md is one lane with verified paths only: clone -> `dotnet build Nexo.Kernel.sln` -> `nexo doctor` -> run Nexo.API on loopback with the mock provider -> `POST /api/copilot/task` and read the record it leaves in `/api/copilot/tasks/{id}` and `/api/trust/dashboard` (curl and Invoke-RestMethod) -> `scripts/run-cert-gate.sh` or the 16-test gate-teeth slice -> what to test and how to report -> known limitations. Every route, DTO, default and file on the page was checked against the code and run. README's top is rewritten under decision D1 (assumed, owner to confirm): Nexo = auditable AI workflows on infrastructure you control; the trust loop is how "auditable" is true, not a separate product; the autonomy loop is experimental and hold-mode; self-hosted only. "Start here" points at the quickstart, the lanes are trimmed, the "autopilot panel" lead is retired (observe/adapt/improve stays as a subsection), a "Trust loop / certification (experimental)" section links the spec, the evidence ledger, the governed pipeline, the sample objective and the first-flight spike with the hold-mode caveat, and the Where-to-start table no longer recommends `--no-restore` as the first command. Regions touched by the in-flight docs/repo-map-refresh branch (Scope in 30 seconds, Subsystem map, Project layout) are left byte-identical. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…rograms historical; document spikes/ docs/DocsIndex.md: Start Here #1 is the tester quickstart, README #2, GettingStarted #3; IntegratorGuide and consumer-template/CONSUMING.md are listed for the first time; RELEASE.md, the setup-matrix scripts and the bootstrap helpers move out of the numbered list into an "escape hatches" paragraph (RELEASE stays under Operator); a new "Trust loop / certification (experimental, hold-mode)" group makes docs/trust-loop/*, the evidence ledger, governed-pipeline, SELF-EXTEND-AUDIT, the sample objective and spikes/ reachable; "Planning & Roadmap" becomes "Planning history (historical as of 2026-08-16)" because it described a finished program. Stale status docs are date-stamped rather than deleted: - ProtocolIntegration-MCP-A2A.md said the Nexo.API wiring was "planned"; it landed in #269/#270 (Program.cs registers all four adapters and maps /api/mcp and /api/a2a/{agentId}; IngressCatalog rows McpServer/A2AAgents). - ci-pre-existing-failures.md said the Full Platform Readiness Gate was RED as of 06-21; it went green with #317-#320/#335. Kept because docs/planning/* still cite it. - GapAnalysis.md and NorthStarGapAnalysis.md predate the trust loop; both get a historical banner naming their still-open rows and pointing at the ledger, ProjectTiers and CHANGELOG. GettingStarted.md #5 contradicted DocsIndex on "installer" scripts (the scripts/install/* helpers exist but bootstrap the container lane); it now says so and points first-run readers at the quickstart. The pointer to a README section "First Successful Pipeline Run" (which does not exist) now names the sections that do. IntegratorGuide.md recommended `dotnet build Nexo.sln` (the docs guard forbids it in README); it now builds Nexo.Kernel.sln and the CLI project, with hello-brick as the smallest test example, and the compatibility matrix names the solutions that actually apply. spikes/README.md: the 27 tracked files under spikes/ were cited as PASS evidence by the ledger but undocumented. It says what each spike is, every flag of the flight runner, which ledger rows cite each spike, and that none of it is a supported entry point. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
….md stops citing a release that does not exist CHANGELOG.md carried a single generic [Unreleased] block untouched by ~50 merges (119 conventional commits) since the file was added on 2026-08-13. The block is now Keep-a-Changelog grouped (Added / Changed / Fixed / Security) from `git log e668215..master`, with PR numbers where a change landed as one PR, and names the wave-1/2 readiness PRs #325-#337. No version is cut and the header sentence the docs/repo-map-refresh branch edits is untouched. SECURITY.md said "only the most recent release and master are supported" while no release has been tagged; it now says master is the only supported line until one is. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ight prerequisites Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
Uh oh!
There was an error while loading. Please reload this page.
IanFrelinger pushed a commit
that referenced
this pull request
Aug 17, 2026
…ckfill + this PR's Contracts entry)
IanFrelinger pushed a commit
that referenced
this pull request
Aug 17, 2026
…tatements updated to 10 (GettingStarted, IntegratorGuide, TesterQuickstart)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Production-readiness audit, M36 + M34 + M35 + M37 + M38 + M44 + L14 + L16 + L17. Ledger: https://claude.ai/code/artifact/15fa4198-97b8-4da6-bea0-0c24d364a7f3
D1 assumption (owner to confirm before merge)
ASSUMED, verbatim: the story that leads is "Nexo: auditable AI workflows on infrastructure you control - every artifact certified, every action on the record." The trust loop (certification gate: analyzer fence -> witness -> mutation -> determinism, plus the hold-mode autonomy loop) is HOW "auditable" is true, not a separate product. Hero demo = "submit a task -> output + audit trail visible" (docs/PayingCustomersASAP.md ~66, docs/CopilotMvpWalkthrough.md), with "hot-reload certified code" as the platform-team showcase. Retire "autopilot panel" / observe-adapt-improve as the LEAD (it can remain a section). Self-hosted only at launch (no Cloud SKU claims); README "not a hosted SaaS" stays true. Autonomy loop is presented as EXPERIMENTAL, hold-mode, with the ledger caveats. Consistent with: lead with control + proof, not "we have agents" (docs/MarketingAndDeploymentPlaybook.md); hero metric "time to first audited job"; anti-ICPs (docs/ICPResearchMemo.md); open-core boundary (docs/OpenCoreBoundary.md).
What this PR does
(a)
docs/TesterQuickstart.md(new) - one lane, verified paths only: clone -> prerequisites (SDK 9, RollForward=Major so no 8.x runtime, Docker optional, mock provider needsNEXO_ALLOW_MOCK=1) ->dotnet build Nexo.Kernel.sln->dotnet run --project application/src/Nexo.CLI -- doctor(with thedocker infono-timeout trap named,application/src/Nexo.CLI/Commands/BootstrapRuntime.cs) -> the hero:NEXO_ALLOW_MOCK=1 dotnet run --project application/src/Nexo.APIonhttp://localhost:5000(exposure fail-closed rule quoted fromProgram.cs),POST /api/copilot/taskwith curl andInvoke-RestMethod, then/api/copilot/tasks/{id},/api/copilot/tasks,/api/trust/dashboard,/api/activity/feed,/api/trust/status-> "see it certify":bash scripts/run-cert-gate.shor the 16-test~CertificationGateTeethTestsslice,samples/hello-brickas the authoring path -> what to test / how to report (three issue templates, SECURITY.md) -> known limitations (ledger "Known v0 limitations", autonomy loop experimental/hold-mode, HTTP-only defaults, nothing on nuget.org).(b)
README.md- top rewritten under D1: one-sentence definition, three-item "what you get" each with the command behind it, "Start here" -> TesterQuickstart, lanes trimmed to one line (+ Integrate), Where-to-start table fixed (--no-restoreno longer the first command; IntegratorGuide + consumer-template added), "Default workflow" + "autopilot panel" lead replaced by Trust loop / certification (experimental) (gate CI-proven / autonomy loop spike-grade + hold-mode, S5 equivalent-mutant caveat; links spec, ledger, governed-pipeline, sample objective, first-flight spike via spikes/README.md, hello-brick, SELF-EXTEND-AUDIT) and a rewritten "Why Nexo" with observe/adapt/improve as a subsection.What Nexo is not,Scope in 30 seconds,Subsystem map,Project layoutuntouched (the latter three are edited by in-flightdocs/repo-map-refresh; unchanged lines separate the hunks, so no conflict).(c)
docs/DocsIndex.md- Start Here #1 TesterQuickstart, IntegratorGuide + consumer-template/CONSUMING.md added, RELEASE.md/setup-matrix/bootstrap helpers demoted to an "escape hatches" paragraph, new Trust loop / certification (experimental, hold-mode) group, ProtocolIntegration entry updated, roadmap block retitled "Planning history (historical as of 2026-08-16)", #14 vs GettingStarted #5 contradiction resolved on both sides.(d) Stale docs -
ProtocolIntegration-MCP-A2A.mdstatus lines (API wiring landed #269/#270, all flagged off);docs/ci-pre-existing-failures.mddate-stamped historical (FPR gate green with #317-#320/#335; kept because docs/planning/* cite it);GapAnalysis.md/NorthStarGapAnalysis.mdretitled historical with banners naming their still-open rows and pointing at the ledger; DocsIndex roadmap. April GTM drafts not moved and not linked from Start Here.(e)
GettingStarted.mdfirst-run pointer + installer-script wording + the dead "First Successful Pipeline Run" pointer;IntegratorGuide.md->Nexo.Kernel.sln/ CLI project / hello-brick, compatibility matrix;CHANGELOG.md[Unreleased]backfilled Keep-a-Changelog style fromgit log e6682152..masternaming #325-#337, no version cut;SECURITY.mdno longer cites a release that does not exist;spikes/README.md(new) - both spikes, every flight-runner flag, ledger rows that cite each, "not a supported entry point".(f) Both
onboarding-docs-guardbash steps run locally over the tree: startup-defaults greps pass; referenced-path guard reports 0 missing.Skipped (with evidence)
CONTRIBUTING.md~95-101 (minimal bar):origin/fix/setup-and-observability(PR 16) already rewrites exactly those lines to the CI-proven lanes;origin/docs/repo-map-refresh(PR 12) rewrites lines 4-14 and 39-50. Left untouched.docs/repo-map-refresh; nothing to keep yet, and this PR does not touch that region.Verification
dotnet build Nexo.Kernel.sln: 0 warnings, 0 errors on this host (SDK 9.0.317).dotnet run --project application/src/Nexo.CLI -- --help: runs.-- doctorhung at thedocker infoprobe on this host because the Docker daemon is not responding (the exact trap the page documents; probe has no timeout,BootstrapRuntime.csWindowsdockerspec). Could not kill/rerun without Docker on PATH (sandbox denied); relying on CI onboarding gates for the PASS line.NEXO_ALLOW_MOCK=1 dotnet run --project application/src/Nexo.API->Now listening on: http://localhost:5000;/health200;POST /api/copilot/task{"task":..,"auditCount":5}->{"taskId":..,"tenantId":"default","success":true,"summary":"1 agent(s) executed","output":{..},"isTrustPaused":false,"recentAudit":[]};/api/copilot/tasks/{id},/api/copilot/tasks,/api/trust/dashboard(eventType=CopilotTask, disposition=Success, sourceId=<taskId>),/api/activity/feed,/api/trust/statusall returned as documented; PowerShellInvoke-RestMethodvariants run verbatim; portal/and/swagger/index.html200.group.MapPost("/copilot/task", RunCopilotTaskAsync)underapp.MapGroup("/api")(NexoEndpoints.cs);public sealed record CopilotTaskRequest(string Task, int AuditCount = 25);(CopilotTaskRequest.cs);CopilotTaskResponse(TaskId, TenantId, Success, Summary, Output, IsTrustPaused, RecentAudit).dotnet test src/Nexo.Tests.Infrastructure/Nexo.Tests.Infrastructure.csproj -f net8.0 --filter "FullyQualifiedName~CertificationGateTeethTests": Passed 16/16 in 1m15s.gh api repos/IanFrelinger/Nexo/branches/master/protection-> required contexts["cert-gate"].Co-Authored-By: Claude Opus 5 noreply@anthropic.com
🤖 Generated with Claude Code