Cynrath · Cynrath · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026
diff --git a/.cursor/rules/project.mdc b/.cursor/rules/project.mdc
@@ -9,6 +9,15 @@
 - Do not include model name, generator, or AI authorship in commit messages.
 - `0.2.0-alpha.3` is published and verified by TASK-0206; do not move the tag, replace assets, republish the version, or manually mutate the GitHub Release/NuGet package.
 
+## NuGet Package README Boundary
+- GitHub repository README: `README.md`.
+- NuGet package README: `README.nuget.md`.
+- Package metadata and package-root README packing live in `src/AgentContextKit.Cli/AgentContextKit.Cli.csproj`.
+- NuGet README validation lives in `scripts/check-package-metadata.ps1`.
+- Documentation mirrors live in `docs/PACKAGING.md` and `docs/NUGET_METADATA.md`.
+- Keep `README.nuget.md` pure Markdown. Do not use raw HTML, GitHub-only alignment/layout, local relative images, or generated artifacts there.
+- Published NuGet package versions cannot be edited in place; nuget.org README fixes become visible only after a later authorized package publish.
+
 ## Commit Completeness Hard Rule
 - Before any push, run `git status` and confirm the working tree is clean.
 - Run `powershell -ExecutionPolicy Bypass -File scripts/check-tracked-vs-untracked-md.ps1 -FailOnIssues` to confirm no tracked source file is left untracked.
@@ -31,4 +40,5 @@
 - `dotnet test AgentContextKit.sln -c Release --no-build`
 - `dotnet run --project src/AgentContextKit.Cli/AgentContextKit.Cli.csproj -c Release --no-build -- scan --ci`
 - `dotnet run --project src/AgentContextKit.Cli/AgentContextKit.Cli.csproj -c Release --no-build -- doctor`
+- `powershell -ExecutionPolicy Bypass -File scripts/check-package-metadata.ps1 -FailOnIssues`
 - `powershell -ExecutionPolicy Bypass -File scripts/verify-release.ps1`
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,7 +1,7 @@
 # AgentContextKit Agent Rules
 
 ## Default Workflow
-- Read `README.md`, `docs/PRODUCT_SPEC.md`, `docs/ARCHITECTURE.md`, and the active task before changing code.
+- Read `README.md`, `README.nuget.md`, `docs/PRODUCT_SPEC.md`, `docs/ARCHITECTURE.md`, and the active task before changing code or package metadata.
 - Use task-first workflow: every implementation change starts from a `docs/tasks/` record.
 - Do not code before a task file exists under `docs/tasks/`.
 - Continuous progress hard rule: when the user says to continue, do not ask whether to continue; proceed through the next documented task in order with task docs, implementation, verification, and commit.
@@ -10,6 +10,15 @@
 - Prefer safe, minimal, production-ready changes.
 - Do not commit generated `.ackit/`, SARIF, HTML, Web UI, prompt pack, context export, `bin/`, or `obj/` artifacts.
 
+## NuGet Package README Boundary
+- GitHub repository presentation lives in root `README.md`.
+- NuGet package presentation lives in root `README.nuget.md`.
+- `src/AgentContextKit.Cli/AgentContextKit.Cli.csproj` owns `PackageReadmeFile` and the explicit package-root packing entry for `README.nuget.md`.
+- Changes intended to fix the nuget.org package page must update `README.nuget.md`, the CLI `.csproj` package metadata, `scripts/check-package-metadata.ps1`, `docs/PACKAGING.md`, and `docs/NUGET_METADATA.md` together.
+- Keep `README.nuget.md` pure Markdown: no raw HTML blocks, no GitHub-only layout markup, no relative local image paths, and no generated report artifacts.
+- Do not try to fix NuGet rendering by weakening or removing the GitHub README layout unless the GitHub README itself is the intended target.
+- A published NuGet version is immutable for this purpose; visible package README corrections require a later authorized package publish.
+
 ## Safety
 - Keep the MVP offline-first and local-only.
 - Do not upload repository content.
@@ -59,8 +68,8 @@
 - Previous release: `v0.2.0-alpha.2` published and verified; pushed, released, and published.
 - NuGet global tool install verification: completed.
 - GitHub Release page: completed.
-- Published-package smoke workflow may still need a post-publish pin sync to `AgentContextKit` `0.2.0-alpha.3`.
-- Source-package smoke workflow installs the local `AgentContextKit` `0.2.0-alpha.3` package.
+- Published-package smoke workflow is pinned to `AgentContextKit` `0.2.0-alpha.3` and TASK-0214 recorded hosted pass evidence.
+- Source-package smoke workflow installs the local `AgentContextKit` package built from source.
 
 ## Risk Summary
 - No risk findings in the latest local scan.
@@ -71,6 +80,7 @@
 - `dotnet test AgentContextKit.sln -c Release --no-build`
 - `dotnet run --project src/AgentContextKit.Cli/AgentContextKit.Cli.csproj -c Release --no-build -- scan --ci`
 - `dotnet run --project src/AgentContextKit.Cli/AgentContextKit.Cli.csproj -c Release --no-build -- doctor`
+- `powershell -ExecutionPolicy Bypass -File scripts/check-package-metadata.ps1 -FailOnIssues`
 - `powershell -ExecutionPolicy Bypass -File scripts/verify-release.ps1`
 
 ## Handoff

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,8 @@ This project follows Semantic Versioning where practical before `1.0.0`.
 ## [Unreleased]
 
 ### Added
+- Added a dedicated pure-Markdown `README.nuget.md` package README and package metadata wiring so nuget.org does not render GitHub README HTML as raw text.
+- Added agent-facing documentation for the split between GitHub `README.md` and NuGet `README.nuget.md` ownership.
 - Added two new stable scanner rule IDs: `ACKIT006` `ProductionConfigLike` (High) for production configuration, environment-specific appsettings, and live-service connection strings, and `ACKIT007` `DocumentationGap` (Medium) for documentation gaps surfaced by the scanner. Existing `ACKIT001` and `ACKIT005` descriptions were narrowed to reflect the new dedicated rules.
 - Added an `Ackit006Ackit007EndToEndTests` coverage class that exercises the Core `RepositoryScanner` on a synthetic `appsettings.Production.json` fixture, asserts the new `ACKIT006` ruleId flows into JSON and the redact-check filter, asserts the catalog mapping for `ACKIT007`, and asserts the SARIF rule catalog advertises the new ID.
 

diff --git a/README.nuget.md b/README.nuget.md
@@ -0,0 +1,87 @@
+# AgentContextKit
+
+Offline-first repository context and safety tooling for AI-assisted development.
+
+AgentContextKit analyzes a repository, generates clean agent context files, creates task-first workflow docs, and catches secret, PII, and brand leakage risks before a project is shared with AI agents or released publicly.
+
+This NuGet README is intentionally plain Markdown so it renders consistently on nuget.org. The richer GitHub README remains in `README.md`.
+
+## Install
+
+Install the current package version shown on nuget.org:
+
+```powershell
+dotnet tool install --global AgentContextKit --version <package-version>
+```
+
+Update an existing global install:
+
+```powershell
+dotnet tool update --global AgentContextKit --version <package-version>
+```
+
+Verify the tool:
+
+```powershell
+ackit version
+ackit --help
+```
+
+## Quick start
+
+Run the local repository health check:
+
+```powershell
+ackit doctor
+```
+
+Scan the current repository for release-blocking context risks:
+
+```powershell
+ackit scan --ci
+```
+
+Create a task-first workflow note:
+
+```powershell
+ackit task "Describe the next focused change"
+```
+
+Generate local agent instructions and context files:
+
+```powershell
+ackit generate --target all
+ackit prompt-pack --output .ackit/prompt-pack.md
+```
+
+## Core commands
+
+| Command | Purpose |
+| --- | --- |
+| `ackit doctor` | Checks repository readiness signals. |
+| `ackit scan --ci` | Scans for secret, PII, brand, artifact, and release-safety findings. |
+| `ackit task "title"` | Creates a task-first workflow document. |
+| `ackit generate --target all` | Generates supported local agent instruction surfaces. |
+| `ackit prompt-pack` | Builds a local Markdown prompt pack for review. |
+| `ackit context-export --approve` | Exports reviewed context after explicit approval. |
+| `ackit sarif --output <file.sarif>` | Writes SARIF for security tooling. |
+| `ackit report --output <file.html>` | Writes a local HTML report. |
+| `ackit watch --once` | Runs the watch-mode scan path once. |
+
+## Safety model
+
+Default commands process repository content locally. They do not upload a repository, call an AI API, send telemetry, or invoke external tools by default.
+
+The tool is designed for a human-reviewed workflow before a repository is handed to Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, or a similar coding agent.
+
+## Documentation
+
+- Project website: https://github.com/Cynrath/agent-context-kit
+- CLI reference: https://github.com/Cynrath/agent-context-kit/blob/master/docs/CLI_REFERENCE.md
+- No-network default policy: https://github.com/Cynrath/agent-context-kit/blob/master/docs/NO_NETWORK_DEFAULT_POLICY.md
+- Security policy: https://github.com/Cynrath/agent-context-kit/security
+- License: MIT
+
+## Package note
+
+The NuGet package uses `README.nuget.md` as `PackageReadmeFile`. Keep this file pure Markdown and avoid raw HTML, local image paths, generated report artifacts, or GitHub-only layout markup.
diff --git a/docs/NUGET_METADATA.md b/docs/NUGET_METADATA.md
@@ -30,6 +30,18 @@ This review follows Microsoft Learn NuGet package authoring guidance for package
 - https://learn.microsoft.com/nuget/create-packages/package-authoring-best-practices#package-metadata
 - https://learn.microsoft.com/nuget/reference/msbuild-targets#pack-target
 
+## NuGet README Rendering Contract
+
+The repository intentionally separates the GitHub README and NuGet package README:
+
+- `README.md` is the GitHub repository README.
+- `README.nuget.md` is the NuGet package README.
+- `src/AgentContextKit.Cli/AgentContextKit.Cli.csproj` owns `PackageReadmeFile` and the explicit package-root packing entry.
+
+Keep `README.nuget.md` pure Markdown. Do not add raw HTML, GitHub-only alignment/layout markup, relative local image paths, generated reports, or package artifacts. If nuget.org rendering breaks, edit `README.nuget.md` and the package metadata/check/docs files together.
+
+A published NuGet version cannot be corrected in place for README rendering. The fix becomes visible on nuget.org only after a later authorized package publish.
+
 ## Metadata Review
 Run report-only mode:
 
@@ -69,7 +81,7 @@ AgentContextKit 0.2.0-alpha.3
 - `Version`: `0.2.0-alpha.3`
 - `Authors`: `Cynrath`
 - `Company`: `Cynrath`
-- `PackageReadmeFile`: `README.md`
+- `PackageReadmeFile`: `README.nuget.md`
 - `PackageLicenseExpression`: `MIT`
 - `RepositoryType`: `git`
 - `RepositoryUrl`: `https://github.com/Cynrath/agent-context-kit`
@@ -78,7 +90,7 @@ AgentContextKit 0.2.0-alpha.3
 - `Description`: non-empty
 - `PackageTags`: includes `ai`, `coding-agent`, `security`, `cli`, and `oss`
 - `PackageReleaseNotes`: non-empty
-- `README.md`: present and explicitly packed into the package root
+- `README.nuget.md`: present and explicitly packed into the package root
 
 ## Future Publish Gates
 Before future public publish after `0.2.0-alpha.3`:

diff --git a/docs/PACKAGING.md b/docs/PACKAGING.md
@@ -11,11 +11,22 @@ Important fields:
 - `Version`: `0.2.0-alpha.3`; current published package is `0.2.0-alpha.3`
 - `Authors`: `Cynrath`
 - `PackageLicenseExpression`: `MIT`
-- `PackageReadmeFile`: `README.md`
+- `PackageReadmeFile`: `README.nuget.md`
 - `RepositoryType`: `git`
 - `RepositoryUrl`: `https://github.com/Cynrath/agent-context-kit`
 - `PackageProjectUrl`: `https://github.com/Cynrath/agent-context-kit`
 
+## README Files
+
+The repository intentionally has two README surfaces:
+
+- `README.md` is the GitHub repository README and may use GitHub-supported layout markup.
+- `README.nuget.md` is the NuGet package README and must stay pure Markdown so nuget.org renders it cleanly.
+
+The NuGet README is wired from `src/AgentContextKit.Cli/AgentContextKit.Cli.csproj` through `PackageReadmeFile` and an explicit package-root packing entry. If the nuget.org README page needs a correction, update `README.nuget.md`, the CLI `.csproj`, `scripts/check-package-metadata.ps1`, and `docs/NUGET_METADATA.md` together.
+
+Published NuGet versions are immutable for README corrections. A visible nuget.org README fix requires a later authorized package publish; do not move tags, replace release assets, or republish an existing version.
+
 Run the dedicated metadata review before pack or publish checks:
 
 ```powershell

diff --git a/docs/tasks/TASK-0215-nuget-readme-rendering.md b/docs/tasks/TASK-0215-nuget-readme-rendering.md
@@ -0,0 +1,55 @@
+# TASK-0215: NuGet README rendering cleanup
+
+## Purpose
+Fix the nuget.org package README rendering problem caused by using the GitHub README as the package README, and make the file ownership obvious to future coding agents.
+
+## Problem
+The GitHub README can use GitHub-supported HTML/layout markup. nuget.org does not render that surface the same way, so raw HTML can appear on the NuGet package page.
+
+## Scope
+- Add a dedicated root `README.nuget.md` for the NuGet package page.
+- Keep root `README.md` as the GitHub repository README.
+- Update `src/AgentContextKit.Cli/AgentContextKit.Cli.csproj` so `PackageReadmeFile` points at `README.nuget.md` and packs that file into the package root.
+- Update `scripts/check-package-metadata.ps1` so the metadata gate validates `README.nuget.md`.
+- Update agent-facing documentation so agents understand that NuGet README changes live in `README.nuget.md` plus the CLI package project metadata.
+- Update packaging and NuGet metadata docs.
+
+## Out of scope
+- No NuGet publish.
+- No GitHub Release mutation.
+- No tag creation, deletion, or movement.
+- No republish of `0.2.0-alpha.3`.
+- No release workflow dispatch.
+- No broad GitHub README redesign.
+
+## Affected files
+- `README.nuget.md`
+- `src/AgentContextKit.Cli/AgentContextKit.Cli.csproj`
+- `scripts/check-package-metadata.ps1`
+- `AGENTS.md`
+- `.cursor/rules/project.mdc`
+- `docs/PACKAGING.md`
+- `docs/NUGET_METADATA.md`
+- `docs/tasks/TASK-0215-nuget-readme-rendering.md`
+
+## Acceptance criteria
+- NuGet package README content is pure Markdown and contains no raw HTML layout blocks.
+- `PackageReadmeFile` points to `README.nuget.md`.
+- `README.nuget.md` is explicitly packed into the package root.
+- Package metadata gate expects `README.nuget.md`.
+- Agent documentation names the exact files/folder paths to edit for NuGet package page changes.
+- Existing published package, tag, and GitHub Release state are not mutated.
+
+## Validation commands
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/check-package-metadata.ps1 -FailOnIssues
+dotnet build AgentContextKit.sln -c Release --no-restore
+dotnet test AgentContextKit.sln -c Release --no-build
+dotnet pack src/AgentContextKit.Cli/AgentContextKit.Cli.csproj -c Release
+```
+
+Package inspection should confirm `README.nuget.md` exists at package root.
+
+## Completion notes
+Pending validation on a local checkout or hosted PR checks. This task intentionally prepares source metadata only; the visible nuget.org page will change after a later authorized package publish.