diff --git a/app/cli/cmd/root.go b/app/cli/cmd/root.go
index 8587910e7..1ec74304a 100644
--- a/app/cli/cmd/root.go
+++ b/app/cli/cmd/root.go
@@ -74,6 +74,12 @@ const (
 
 	trueString                      = "true"
 	supportsFederatedAuthAnnotation = "supportsFederatedAuth"
+
+	// cliReferenceURL is the generated reference for the commands in this
+	// repository. It is generated by app/cli/documentation and read there: the
+	// documentation site publishes the Enterprise Edition reference instead, so
+	// linking to it would send users to a page that documents other commands.
+	cliReferenceURL = "https://github.com/chainloop-dev/chainloop/blob/main/app/cli/documentation/cli-reference.md"
 )
 
 var telemetryWg sync.WaitGroup
@@ -104,8 +110,14 @@ func NewRootCmd(l zerolog.Logger) *cobra.Command {
 	logger = l
 
 	rootCmd := &cobra.Command{
-		Use:           appName,
-		Short:         "Chainloop Command Line Interface",
+		Use:   appName,
+		Short: "Chainloop Command Line Interface",
+		// The generated reference for these commands is kept in this repository
+		// rather than published to the documentation site, so the link points at
+		// the file itself.
+		Long: `Chainloop Command Line Interface
+
+Command reference: ` + cliReferenceURL,
 		SilenceErrors: true,
 		SilenceUsage:  true,
 		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
@@ -459,7 +471,7 @@ var (
 	// Posthog API key and endpoint are not sensitive information, they represent Chainloop's
 	// Posthog instance. Both are overridable at build time with -X so anyone compiling the CLI
 	// can point it at their own instance, and telemetry can be turned off entirely with
-	// DO_NOT_TRACK=1. See https://docs.chainloop.dev/command-line-reference/cli-telemetry.
+	// DO_NOT_TRACK=1. See https://docs.chainloop.dev/cli/telemetry.
 	//
 	// The endpoint is compiled in and has no runtime override, so an installed binary reports
 	// wherever it was built to report. https://crb.chainloop.dev is therefore frozen on the
diff --git a/app/cli/cmd/trace_init.go b/app/cli/cmd/trace_init.go
index 206dfc49d..e6b946620 100644
--- a/app/cli/cmd/trace_init.go
+++ b/app/cli/cmd/trace_init.go
@@ -214,7 +214,7 @@ The organization, project, workflow and require-trace values are saved to
 
 // traceDocsURL is the guide covering what this command set up and what can be
 // done with it, which is more than belongs in a command's own output.
-const traceDocsURL = "https://docs.chainloop.dev/guides/chainloop-trace"
+const traceDocsURL = "https://docs.chainloop.dev/ai-sessions"
 
 // writeTraceInitSummary reports what the repository was set up with. It goes to
 // stdout rather than through the logger because it is the command's result,
diff --git a/app/cli/documentation/cli-reference.mdx b/app/cli/documentation/cli-reference.md
old mode 100755
new mode 100644
similarity index 99%
rename from app/cli/documentation/cli-reference.mdx
rename to app/cli/documentation/cli-reference.md
index 18995514d..7ca0e9c10
--- a/app/cli/documentation/cli-reference.mdx
+++ b/app/cli/documentation/cli-reference.md
@@ -1,10 +1,6 @@
----
-title: Command Line Reference (OSS)
----
+# Command Line Reference (OSS)
 
-<Note>
-[The Enterprise Edition CLI](/command-line-reference/cli-ee-reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing).
-</Note>
+> [The Enterprise Edition CLI](https://docs.chainloop.dev/cli/reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing).
 
 Chainloop CLI is a command-line tool designed to streamline the process of crafting, managing, and storing software supply chain attestations. The CLI enables developers to generate and submit evidence-such as build artifacts, SBOMs, 
 and vulnerability reports-directly from their CI/CD workflows, ensuring compliance with organizational policies without introducing friction into the development process.
diff --git a/app/cli/documentation/generate.go b/app/cli/documentation/generate.go
index 3459c4efc..df429c9b6 100644
--- a/app/cli/documentation/generate.go
+++ b/app/cli/documentation/generate.go
@@ -1,5 +1,5 @@
 //
-// Copyright 2025 The Chainloop Authors.
+// Copyright 2025-2026 The Chainloop Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -30,13 +30,12 @@ import (
 	"github.com/spf13/cobra/doc"
 )
 
-const fileHeader = `---
-title: Command Line Reference (OSS)
----
+// fileHeader is plain Markdown rather than MDX: this reference is read in the
+// repository, not published to the documentation site, so it carries its own
+// title instead of front matter and links out with absolute URLs.
+const fileHeader = `# Command Line Reference (OSS)
 
-<Note>
-[The Enterprise Edition CLI](/command-line-reference/cli-ee-reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing).
-</Note>
+> [The Enterprise Edition CLI](https://docs.chainloop.dev/cli/reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing).
 
 Chainloop CLI is a command-line tool designed to streamline the process of crafting, managing, and storing software supply chain attestations. The CLI enables developers to generate and submit evidence-such as build artifacts, SBOMs, 
 and vulnerability reports-directly from their CI/CD workflows, ensuring compliance with organizational policies without introducing friction into the development process.
@@ -68,7 +67,10 @@ func main() {
 	formatted := processFinalDocument(builder.String())
 	withHeader := fmt.Sprintf("%s%s", fileHeader, formatted)
 
-	err := os.WriteFile(filepath.Join(out, "cli-reference.mdx"), []byte(withHeader), 0600)
+	// The output directory is the argument in this file's go:generate directive,
+	// not anything a user of the CLI controls.
+	// nolint:gosec
+	err := os.WriteFile(filepath.Join(out, "cli-reference.md"), []byte(withHeader), 0600)
 	if err != nil {
 		log.Fatal(err)
 	}
diff --git a/docs/examples/policies/quickstart/README.md b/docs/examples/policies/quickstart/README.md
index ed20e198f..3c39187d1 100644
--- a/docs/examples/policies/quickstart/README.md
+++ b/docs/examples/policies/quickstart/README.md
@@ -4,7 +4,7 @@ This quickstart guide walks you through creating and validating a basic Chainloo
 
 ## Documentation References
 
-- **CLI Reference**: [chainloop policy develop commands](https://docs.chainloop.dev/command-line-reference/cli-reference#chainloop-policy)
+- **CLI Reference**: [chainloop policy develop commands](https://docs.chainloop.dev/cli/reference#chainloop-policy)
 - **Policy Concepts**: [Understanding Chainloop Policies](https://docs.chainloop.dev/concepts/policies)
 - **Custom Policy Guide**: [Writing Custom Policies](https://docs.chainloop.dev/guides/custom-policies)
 - **Material Types**: [Available Material Types](https://docs.chainloop.dev/concepts/material-types#material-types)