Publish alpha module release chain

README.md

@@ -9,6 +9,9 @@ It is designed for AI agents, CI systems, and human reviewers to work from the s
 
 > Status: pre-alpha. The public repository is being prepared for the first source import under `github.com/nucleuskit/nucleus`.
 
+For a code-level view of what is implemented, what is scaffold-only, and the
+current module release status, see [Implementation Status](docs/implementation-status.md).
+
 ## Why Nucleus
 
 Traditional Go microservice frameworks are optimized for humans writing code inside an IDE. Nucleus is optimized for AI agents changing services safely and repeatably.

cmd/nucleus/internal/initcmd/command_test.go

@@ -23,7 +23,9 @@ func TestCommandServiceTemplateProducesVerifiableProject(t *testing.T) {
 	assertContains(t, output.Files, "nucleus.yaml")
 	assertContains(t, output.Files, "contract/gen/.nucleus-source.sha256")
 	assertContains(t, output.Files, "internal/adapter/http/gen/.nucleus-source.sha256")
-	assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/http v0.1.0-alpha.1.0.20260615170339-225ca98f40d7")
+	assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/http v0.1.0-alpha.2")
+	assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/cap v0.1.0-alpha.2 // indirect")
+	assertFileContains(t, dir, "go.mod", "github.com/nucleuskit/core v0.1.0-alpha.2 // indirect")
 	assertFileNotContains(t, dir, "go.mod", "replace ")
 	assertFileNotContains(t, dir, "api/errors.yaml", "code: 0")
 	assertFileContains(t, dir, "internal/adapter/http/gen/routes.gen.go", `runtimehttp "github.com/nucleuskit/http"`)

cmd/nucleus/internal/initcmd/constants.go

@@ -32,7 +32,11 @@ const (
 	resultKindInit = "nucleus.init_result"
 
 	nucleusHTTPModule      = "github.com/nucleuskit/http"
-	nucleusHTTPVersion     = "v0.1.0-alpha.1.0.20260615170339-225ca98f40d7"
+	nucleusHTTPVersion     = "v0.1.0-alpha.2"
+	nucleusCapModule       = "github.com/nucleuskit/cap"
+	nucleusCapVersion      = "v0.1.0-alpha.2"
+	nucleusCoreModule      = "github.com/nucleuskit/core"
+	nucleusCoreVersion     = "v0.1.0-alpha.2"
 	contractGenTarget      = "contract/gen"
 	httpAdapterGenTarget   = "internal/adapter/http/gen"
 	generatedFreshnessFile = ".nucleus-source.sha256"

cmd/nucleus/internal/initcmd/templates.go

@@ -20,9 +20,14 @@ func templateFiles(templateType string, name string, module string) (map[string]
 }
 
 func serviceTemplateFiles(name string, module string) map[string]string {
+	runtimeRequirements := []moduleRequirement{
+		{Path: nucleusHTTPModule, Version: nucleusHTTPVersion},
+		{Path: nucleusCapModule, Version: nucleusCapVersion, Indirect: true},
+		{Path: nucleusCoreModule, Version: nucleusCoreVersion, Indirect: true},
+	}
 	return map[string]string{
-		"go.mod":                      goModTemplate(module, []moduleRequirement{{Path: nucleusHTTPModule, Version: nucleusHTTPVersion}}),
-		"go.sum":                      goSumTemplate([]string{nucleusHTTPModule}),
+		"go.mod":                      goModTemplate(module, runtimeRequirements),
+		"go.sum":                      goSumTemplate([]string{nucleusHTTPModule, nucleusCapModule, nucleusCoreModule}),
 		"nucleus.yaml":                serviceManifestTemplate(name),
 		"api/openapi.yaml":            openAPITemplate(name),
 		"api/errors.yaml":             serviceErrorsTemplate(),
@@ -75,8 +80,9 @@ func libraryTemplateFiles(name string, module string) map[string]string {
 }
 
 type moduleRequirement struct {
-	Path    string
-	Version string
+	Path     string
+	Version  string
+	Indirect bool
 }
 
 func goModTemplate(module string, requires []moduleRequirement) string {
@@ -88,21 +94,35 @@ func goModTemplate(module string, requires []moduleRequirement) string {
 	}
 	if len(requires) == 1 {
 		item := requires[0]
-		builder.WriteString("\nrequire " + item.Path + " " + item.Version + "\n")
+		builder.WriteString("\nrequire " + formatModuleRequirement(item) + "\n")
 		return builder.String()
 	}
 	builder.WriteString("\nrequire (\n")
 	for _, item := range requires {
-		builder.WriteString("\t" + item.Path + " " + item.Version + "\n")
+		builder.WriteString("\t" + formatModuleRequirement(item) + "\n")
 	}
 	builder.WriteString(")\n")
 	return builder.String()
 }
 
+func formatModuleRequirement(item moduleRequirement) string {
+	line := item.Path + " " + item.Version
+	if item.Indirect {
+		line += " // indirect"
+	}
+	return line
+}
+
 func goSumTemplate(modules []string) string {
 	entries := map[string]string{
-		nucleusHTTPModule: `github.com/nucleuskit/http v0.1.0-alpha.1.0.20260615170339-225ca98f40d7 h1:wWoSiKv5HihOSOstvkov883PfSKLveAuW3tTZb9dH/Q=
-github.com/nucleuskit/http v0.1.0-alpha.1.0.20260615170339-225ca98f40d7/go.mod h1:M4WW38dQuFNIm2kf1O5JIrat+KKZ3ONarUyrtbMDmJo=
+		nucleusHTTPModule: `github.com/nucleuskit/http v0.1.0-alpha.2 h1:YedMdKWg/YkouBOHu3hQvi4Vd8S6YNbdJFPUrzja+Og=
+github.com/nucleuskit/http v0.1.0-alpha.2/go.mod h1:SxCsV2Ag3rtX82BbyIGN7ByiioUePbesFbIKIQQbeRs=
+`,
+		nucleusCapModule: `github.com/nucleuskit/cap v0.1.0-alpha.2 h1:UnBp5ezoi+UrgT92DwpTdQynrEnUNnsf3rQKB0pNfPw=
+github.com/nucleuskit/cap v0.1.0-alpha.2/go.mod h1:DLSQmS/6irYQfpWGJjce9+STvqG33yZMCxkwvdLf7XM=
+`,
+		nucleusCoreModule: `github.com/nucleuskit/core v0.1.0-alpha.2 h1:CT4RJvCYtVNo0+Gqyf5zx4T90dBiXq4JVhQxEKBXyJ8=
+github.com/nucleuskit/core v0.1.0-alpha.2/go.mod h1:fwIlIS28wLh/VQ/jhR4TgrZcrN1nOgrAxSYYYWRdEYk=
 `,
 	}
 	var builder strings.Builder
@@ -292,7 +312,7 @@ func New(cfg config.Config) *App {
 	return &App{
 		config: cfg,
 		router: router,
-		server: serverpkg.NewHTTPServer(cfg.Server.Addr, router),
+		server: serverpkg.NewHTTPServer(cfg.Server.Addr, router.Handler()),
 	}
 }
 

cmd/nucleus/internal/repair/repair_test.go

@@ -20,7 +20,12 @@ ai:
 capabilities:
   - http
 `)
-	writeFile(t, dir, "go.mod", "module example.com/demo\n\ngo 1.26.3\n\nrequire github.com/nucleuskit/http v0.0.0\n\nreplace github.com/nucleuskit/http => "+runtimeHTTPReplace(t)+"\n")
+	writeFile(t, dir, "go.mod", "module example.com/demo\n\ngo 1.26.3\n\nrequire github.com/nucleuskit/http v0.0.0\n\nrequire (\n\tgithub.com/nucleuskit/cap v0.1.0-alpha.2 // indirect\n\tgithub.com/nucleuskit/core v0.1.0-alpha.2 // indirect\n)\n\n"+localRuntimeReplace(t))
+	writeFile(t, dir, "go.sum", `github.com/nucleuskit/cap v0.1.0-alpha.2 h1:UnBp5ezoi+UrgT92DwpTdQynrEnUNnsf3rQKB0pNfPw=
+github.com/nucleuskit/cap v0.1.0-alpha.2/go.mod h1:DLSQmS/6irYQfpWGJjce9+STvqG33yZMCxkwvdLf7XM=
+github.com/nucleuskit/core v0.1.0-alpha.2 h1:CT4RJvCYtVNo0+Gqyf5zx4T90dBiXq4JVhQxEKBXyJ8=
+github.com/nucleuskit/core v0.1.0-alpha.2/go.mod h1:fwIlIS28wLh/VQ/jhR4TgrZcrN1nOgrAxSYYYWRdEYk=
+`)
 	writeFile(t, dir, "demo.go", "package demo\n")
 	writeFile(t, dir, "internal/app/routes.go", `package app
 
@@ -374,3 +379,8 @@ func runtimeHTTPReplace(t *testing.T) string {
 	}
 	return filepath.ToSlash(path)
 }
+
+func localRuntimeReplace(t *testing.T) string {
+	t.Helper()
+	return "replace github.com/nucleuskit/http => " + runtimeHTTPReplace(t) + "\n"
+}

docs/implementation-status.md

@@ -0,0 +1,89 @@
+# Implementation Status
+
+This document records what the current checkout actually implements. It is meant
+to keep the public positioning honest: Nucleus is an AI-first microservice
+kernel, not a production-complete replacement for go-zero, Kratos, go-kit, or a
+full middleware platform.
+
+## Status Key
+
+| Status | Meaning |
+| --- | --- |
+| Implemented | Code exists, has tests, and is expected to work in the current checkout. |
+| Published alpha | Code is available through published alpha module tags without local `replace` directives. |
+| Scaffold | The CLI generates service-owned code or metadata, but does not wire a real provider automatically. |
+| Fake/static | Useful for local tests, examples, or metadata checks; not a real external provider integration. |
+| Metadata-only | Produces inspection or readiness evidence without starting business handlers or provider SDKs. |
+
+## CLI Surface
+
+| Command | Current status | Notes |
+| --- | --- | --- |
+| `nucleus init` | Implemented | Generates service, worker, and library templates. The service template is covered by tests that run validation, strict lint, and `go test ./...`. |
+| `nucleus validate` | Implemented | Validates `nucleus.yaml`, `api/openapi.yaml`, `api/errors.yaml`, and lightweight proto facts. |
+| `nucleus gen` | Implemented | Generates contract metadata, HTTP route binders, gRPC metadata, error metadata, docs, TypeScript schema exports, and minimal clients. |
+| `nucleus lint` | Implemented | Checks architecture boundaries, route registration, capability graph, generated freshness, schema versions, and selected legacy imports. |
+| `nucleus verify` | Implemented | Runs validate, strict lint, generated freshness, `go mod tidy`, import, build, and tests as evidence steps. |
+| `nucleus describe` | Implemented | Emits manifest, contract, capability, module, edit-surface, freshness, and verification facts. |
+| `nucleus plan` | Implemented | Produces task-oriented edit surfaces, commands, and risk notes. Natural-language classification is heuristic. |
+| `nucleus apply` | Implemented | Applies plan file edits only after edit-surface, path traversal, and symlink checks. It deliberately does not execute shell commands. |
+| `nucleus repair` | Implemented | Supports bounded repair for generated freshness and single explicit patch candidates with expected hashes. It is not a general code-repair engine. |
+| `nucleus scenario` | Implemented | Builds OpenAPI/error-derived scenario suggestions and can run explicit HTTP scenario checks when a base URL or handler is provided. |
+| `nucleus serve` | Metadata-only | Serves `/healthz`, `/readyz`, and `/.well-known/nucleus.json` metadata. It does not start generated business handlers. |
+| `nucleus report` | Metadata-only | Summarizes local AI task quality and platform-readiness metadata without network calls. |
+| `nucleus migrate` | Metadata-only | Produces migration checklists and readiness checks. It does not rewrite services. |
+| `nucleus capability add` | Scaffold | Updates manifest metadata and generates service-owned component/app/docs scaffolds. Most providers still need explicit bridge wiring by the service. |
+
+## Contract and Manifest Layer
+
+| Area | Current status | Notes |
+| --- | --- | --- |
+| Manifest parsing | Implemented | Uses structured YAML parsing and validates required service metadata, capability names, dependencies, and AI edit surfaces. |
+| OpenAPI inspection | Implemented | Loads route metadata, parameters, request-body facts, examples, and validation hints from `api/openapi.yaml`. It is a lightweight metadata parser, not a complete OpenAPI toolchain. |
+| Proto inspection | Implemented | Extracts package, service, method, streaming, and `google.api.http` facts with a lightweight parser. It is not a replacement for `protoc`. |
+| Error catalog | Implemented | Validates stable error codes, messages, and HTTP status mappings from `api/errors.yaml`. |
+| Generated freshness | Implemented | Compares contract source hashes with generated target markers declared in `ai.generated`. |
+
+## Runtime Modules
+
+| Module | Current status | Notes |
+| --- | --- | --- |
+| `github.com/nucleuskit/http` | Published alpha | HTTP server, route registration, response envelopes, middleware, clients, CORS, SSE, static assets, and well-known metadata are implemented and tested. |
+| `github.com/nucleuskit/grpc` | Published alpha | gRPC server/client wrappers, discovery resolver support, health/reflection options, and interceptor chains are implemented and tested. |
+| `github.com/nucleuskit/worker` | Published alpha | Cron, interval, batch, consumer, stream, map-reduce, timing-wheel, hooks, and manager primitives are implemented and tested. |
+
+The runtime modules use canonical imports such as `github.com/nucleuskit/cap`
+and `github.com/nucleuskit/core`, and the current alpha tags are verified
+without local replacements.
+
+## Capabilities and Bridges
+
+| Area | Current status | Notes |
+| --- | --- | --- |
+| `github.com/nucleuskit/cap` | Implemented | Small capability interfaces, options, no-op implementations, and tests exist for auth, config, discovery, health, HTTP client, KV, lock, log, metric, Mongo, MQ, profiler, Redis, Sentinel, SQL, store, trace, and transport. |
+| In-memory/test bridges | Fake/static | `memory`, `memorylock`, `redis`, `kv`, and several health/config helpers are useful for tests and local examples. They should not be presented as external managed services. |
+| Real provider bridges | Implemented | `goredis`, `sarama`, `sql`, `gorm`, `zap`, `otel`, `prometheus`, `redislock`, and `nacosofficial` contain real provider-facing adapter code and tests. |
+| Static provider bridges | Fake/static | `nacos` provides local/static config and discovery behavior. It is not the official Nacos SDK integration. |
+| Provider scaffolds | Scaffold | `capability add` records provider intent and generates service-owned compile-safe code. Except for the focused PostgreSQL scaffold, it does not automatically import or wire provider SDKs. |
+
+## Examples
+
+The checked-in `examples/service`, `examples/worker`, and `examples/library`
+directories describe templates rather than hosting full generated services. To
+inspect a runnable service today, generate one with:
+
+```bash
+nucleus init --template service --name demo-api --module example.com/demo-api --dir ./demo-api
+cd ./demo-api
+nucleus validate --dir .
+nucleus lint --dir . --strict
+nucleus verify --dir . --json
+go test ./...
+```
+
+## Adoption Guidance
+
+Use the current checkout as an AI-safe contract, manifest, generation, and
+evidence loop. Treat it as a production framework replacement only after more
+real services have validated the runtime modules, bridge modules, examples, and
+upgrade path under production-like constraints.

examples/service/README.md

@@ -1,6 +1,9 @@
 # Nucleus Service Template
 
-Generated by:
+This directory documents the generated service template. It is not itself a
+checked-in runnable generated service.
+
+Generate a runnable service with:
 
 ```bash
 nucleus init --template service --name demo-api --module example.com/demo-api --dir ./demo-api
@@ -16,4 +19,14 @@ The generated service includes:
 - `configs/config.example.yaml`, `docs/`, `deploy/`, and `test/integration/` scaffolding.
 - `AGENTS.md` with business-service edit rules and top-level directory registration.
 
-Run `nucleus gen --dir .`, `nucleus lint --dir . --strict`, `nucleus verify --dir . --json`, and `go test ./...` after contract or implementation changes.
+From the generated service directory, run:
+
+```bash
+nucleus validate --dir .
+nucleus lint --dir . --strict
+nucleus verify --dir . --json
+go test ./...
+```
+
+See [Implementation Status](../../docs/implementation-status.md) for the current
+module and adapter status.

go.mod

@@ -3,14 +3,12 @@ module github.com/nucleuskit/nucleus
 go 1.26.3
 
 require (
-	github.com/nucleuskit/contract v0.1.0-alpha.2
+	github.com/nucleuskit/contract v0.1.0-alpha.3
 	github.com/spf13/cobra v1.10.2
+	go.yaml.in/yaml/v3 v3.0.4
 )
 
 require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
-	go.yaml.in/yaml/v3 v3.0.4 // indirect
 )
-
-replace github.com/nucleuskit/contract => ./contract

go.sum

@@ -1,6 +1,8 @@
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/nucleuskit/contract v0.1.0-alpha.3 h1:RVa63tU3SZGrmVtX8vYP6RQHRLH4p28oLQKv1/kNI04=
+github.com/nucleuskit/contract v0.1.0-alpha.3/go.mod h1:AVLCb1uBSCvd2CLoNvwUqsYN66sF6LWuKkLTeM4WjTk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=