docs(core): annotate shared CLI and generator helpers

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: tae2089

internal/annotation/normalizer.go

@@ -83,6 +83,8 @@ func stripBlockDelimiters(text string, language string) string {
 	return text
 }
 
+// stripPythonDocstringDelimiters removes triple-quote wrappers from a Python docstring body.
+// @intent expose the raw docstring text by trying both """ and ''' triple-quote forms.
 func stripPythonDocstringDelimiters(text string) (string, bool) {
 	for _, quote := range []string{"\"\"\"", "'''"} {
 		if stripped, ok := stripPythonQuotedString(text, quote); ok {
@@ -92,6 +94,8 @@ func stripPythonDocstringDelimiters(text string) (string, bool) {
 	return "", false
 }
 
+// stripPythonQuotedString removes a matching opening and closing quote pair while validating any string prefix.
+// @intent accept docstrings with optional `r` or `u` prefixes without altering body content.
 func stripPythonQuotedString(text string, quote string) (string, bool) {
 	lower := strings.ToLower(text)
 	idx := strings.Index(lower, quote)
@@ -110,6 +114,8 @@ func stripPythonQuotedString(text string, quote string) (string, bool) {
 	return text[idx+len(quote) : len(text)-len(quote)], true
 }
 
+// isSupportedPythonDocstringPrefix accepts only the empty prefix and the raw/unicode docstring prefixes.
+// @intent avoid stripping byte-string or formatted-string docstrings whose escapes need different handling.
 func isSupportedPythonDocstringPrefix(prefix string) bool {
 	if prefix == "" {
 		return true

internal/cli/migrate.go

@@ -11,6 +11,7 @@ import (
 )
 
 // MigrateConfig contains the database and external migration source settings.
+// @intent carry the driver, DSN, and migration source needed for one explicit schema migration run.
 type MigrateConfig struct {
 	DBDriver      string
 	DBDSN         string
@@ -53,6 +54,7 @@ func newMigrateCmd(deps *Deps) *cobra.Command {
 	return cmd
 }
 
+// @intent resolve migration directory precedence between flag, config, and environment defaults.
 func resolveMigrationsDir(cmd *cobra.Command, flagValue string) string {
 	if cmd.Flags().Changed("migrations-dir") {
 		return flagValue

internal/cli/serve.go

@@ -42,6 +42,9 @@ type ServeConfig struct {
 	WebhookFailOnUnreadable bool
 }
 
+// validateServeConfig checks that the serve configuration is self-consistent.
+// @intent reject invalid flag combinations before the server starts
+// @requires cfg.Transport is set; webhook fields are only validated when Transport == "streamable-http"
 func validateServeConfig(cfg ServeConfig) error {
 	if cfg.Transport != "streamable-http" {
 		return nil
@@ -92,6 +95,8 @@ func validateServeConfig(cfg ServeConfig) error {
 	return nil
 }
 
+// configuredCloneBaseURLs merges the singular and plural clone base URL flags into a deduplicated list.
+// @intent normalize clone base URL inputs from both legacy and current flags into a single ordered slice
 func configuredCloneBaseURLs(cfg ServeConfig) []string {
 	baseURLs := append([]string(nil), cfg.RepoCloneBaseURLs...)
 	if cfg.RepoCloneBaseURL != "" {
@@ -171,6 +176,8 @@ func newServeCmd(deps *Deps) *cobra.Command {
 	return cmd
 }
 
+// envInt reads an integer from an environment variable, returning fallback if unset or unparseable.
+// @intent provide env-based defaults for webhook worker flags without panicking on bad input
 func envInt(name string, fallback int) int {
 	raw := strings.TrimSpace(os.Getenv(name))
 	if raw == "" {
@@ -183,11 +190,15 @@ func envInt(name string, fallback int) int {
 	return v
 }
 
+// envIsSet reports whether an environment variable is present in the process environment.
+// @intent distinguish between an unset variable and one explicitly set to empty string
 func envIsSet(name string) bool {
 	_, ok := os.LookupEnv(name)
 	return ok
 }
 
+// envDuration reads a time.Duration from an environment variable, returning fallback if unset or unparseable.
+// @intent provide env-based defaults for webhook timeout and retry delay flags without panicking on bad input
 func envDuration(name string, fallback time.Duration) time.Duration {
 	raw := strings.TrimSpace(os.Getenv(name))
 	if raw == "" {

internal/ctxns/namespace.go

@@ -3,10 +3,14 @@ package ctxns
 
 import "context"
 
+// ctxKey is the unexported type used as the namespace context key to avoid collisions.
+// @intent isolate the namespace value in the context map from any other package's keys.
 type ctxKey struct{}
 
 const DefaultNamespace = "default"
 
+// Normalize replaces an empty namespace with DefaultNamespace, leaving other values unchanged.
+// @intent guarantee callers always observe a non-empty namespace string for store and query layers.
 func Normalize(ns string) string {
 	if ns == "" {
 		return DefaultNamespace

internal/docs/generator.go

@@ -109,6 +109,8 @@ func (g *Generator) RunIndex() error {
 	return g.writeIndex(groups)
 }
 
+// validateDocGroups checks that every group's output path is safe before writing begins.
+// @intent prevent path-traversal writes before any file I/O is attempted
 func (g *Generator) validateDocGroups(groups []nodeGroup) error {
 	for _, grp := range groups {
 		if _, err := safeDocOutputPath(g.OutDir, grp.FilePath+".md"); err != nil {
@@ -177,6 +179,8 @@ func (g *Generator) loadEdges(nodeIDs []uint) (map[uint][]model.Edge, error) {
 	return result, nil
 }
 
+// generatedFiles builds the list of output paths that this run will produce.
+// @intent track expected output files so the manifest and prune step stay consistent
 func generatedFiles(groups []nodeGroup) []string {
 	files := make([]string, 0, len(groups)+1)
 	for _, grp := range groups {
@@ -186,6 +190,8 @@ func generatedFiles(groups []nodeGroup) []string {
 	return files
 }
 
+// manifestPath returns the namespace-scoped path for the docs manifest file.
+// @intent isolate manifest files per namespace so concurrent namespaces do not collide
 func (g *Generator) manifestPath() string {
 	name := ".ccg-docs-manifest.json"
 	if g.Namespace != "" {
@@ -194,6 +200,8 @@ func (g *Generator) manifestPath() string {
 	return filepath.Join(g.OutDir, name)
 }
 
+// loadManifest reads the previously saved manifest from disk, returning an empty manifest if none exists.
+// @intent restore the prior output file list so Run can compute stale files to prune
 func (g *Generator) loadManifest() (*manifest, error) {
 	m := &manifest{Namespace: g.Namespace}
 	data, err := os.ReadFile(g.manifestPath())
@@ -209,6 +217,9 @@ func (g *Generator) loadManifest() (*manifest, error) {
 	return m, nil
 }
 
+// saveManifest persists the list of generated files to disk for use by the next run's prune step.
+// @intent record which files were written so future runs can detect and remove stale docs
+// @sideEffect writes .ccg-docs-manifest[.namespace].json to g.OutDir
 func (g *Generator) saveManifest(files []string) error {
 	data, err := json.MarshalIndent(manifest{Namespace: g.Namespace, Files: files}, "", "  ")
 	if err != nil {
@@ -220,6 +231,10 @@ func (g *Generator) saveManifest(files []string) error {
 	return atomicWriteFile(g.manifestPath(), data, 0644)
 }
 
+// pruneManaged deletes previously generated docs that are no longer in the current output set,
+// but only if the file starts with the managed marker to avoid removing user-edited files.
+// @intent clean up stale generated docs without touching manually created files
+// @sideEffect removes markdown files from g.OutDir that are no longer part of the current graph
 func (g *Generator) pruneManaged(previous, current []string) error {
 	keep := map[string]bool{}
 	for _, p := range current {