Merge pull request #1821 from entireio/feat/agent-help-examples-and-injection-invariant

feat(agent-help): teach agents entire usage via examples + injected invariant

Author: gtrrz-victor

cmd/entire/cli/agent_help_cmd.go

@@ -204,6 +204,7 @@ type agentHelpJSON struct {
 	Command     string                    `json:"command"`
 	Short       string                    `json:"short,omitempty"`
 	Long        string                    `json:"long,omitempty"`
+	Example     string                    `json:"example,omitempty"`
 	Repo        string                    `json:"repo,omitempty"`
 	Flags       []agentHelpFlagJSON       `json:"flags,omitempty"`
 	Subcommands []agentHelpSubcommandJSON `json:"subcommands,omitempty"`
@@ -215,6 +216,7 @@ func renderAgentHelpJSON(rootCmd, target *cobra.Command, repoLine string, trails
 		Command: target.CommandPath(),
 		Short:   target.Short,
 		Long:    strings.TrimSpace(target.Long),
+		Example: strings.TrimSpace(target.Example),
 		Repo:    repoLine,
 	}
 	if target != rootCmd {
@@ -298,6 +300,11 @@ func renderAgentHelpCommand(cmd *cobra.Command, repoLine string, trailsEnabled b
 		b.WriteString(long)
 		b.WriteString("\n")
 	}
+	if example := strings.TrimSpace(cmd.Example); example != "" {
+		b.WriteString("\nExamples:\n")
+		b.WriteString(example)
+		b.WriteString("\n")
+	}
 	b.WriteString("\n")
 	b.WriteString(agentHelpRepoBlock(repoLine))
 

cmd/entire/cli/agent_help_cmd_test.go

@@ -384,6 +384,38 @@ func TestRenderAgentHelpCommand_ShowsFlagsAndSubcommands(t *testing.T) {
 	}
 }
 
+// A command's Example field must reach agents in both output modes: agent-help
+// is the only surface agents read, and an example is what removes arg-format
+// guesswork (e.g. <file>:<line>).
+func TestRenderAgentHelpCommand_RendersExample(t *testing.T) {
+	t.Parallel()
+
+	cmd := &cobra.Command{
+		Use:     "why <file>[:line]",
+		Short:   "Show why a line exists",
+		Example: "  entire why src/auth.go:42 --json",
+	}
+
+	text := renderAgentHelpCommand(cmd, agentHelpTestRepo, true)
+	if !strings.Contains(text, "Examples:") || !strings.Contains(text, "entire why src/auth.go:42 --json") {
+		t.Fatalf("text agent-help must render the example:\n%s", text)
+	}
+
+	root := &cobra.Command{Use: "entire"}
+	root.AddCommand(cmd)
+	jsonOut, err := renderAgentHelpJSON(root, cmd, agentHelpTestRepo, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var doc agentHelpJSON
+	if err := json.Unmarshal([]byte(jsonOut), &doc); err != nil {
+		t.Fatalf("json agent-help must parse: %v\n%s", err, jsonOut)
+	}
+	if doc.Example != "entire why src/auth.go:42 --json" {
+		t.Fatalf("json agent-help must carry the trimmed example, got %q", doc.Example)
+	}
+}
+
 // The top-level rendering lists the live command map (including the revealed
 // trail command), states the auto-detected repo, and carries the standing rule.
 func TestRenderAgentHelpTop_ListsCommandsRepoAndRule(t *testing.T) {

cmd/entire/cli/attribution.go

@@ -149,10 +149,11 @@ func newBlameCmd() *cobra.Command {
 		// Hidden from `entire help` while the feature is still maturing —
 		// advertised under `entire labs`, and `entire blame` / `entire blame
 		// --help` keep working normally.
-		Hidden: true,
-		Short:  "Show which lines came from Entire checkpoints",
-		Long:   "Show git-blame-style line attribution enriched with Entire checkpoint metadata.\n\nLimit to a line or range with <file>:12, <file>:12-20, or the --line flag.",
-		Args:   cobra.ExactArgs(1),
+		Hidden:  true,
+		Short:   "Show which lines came from Entire checkpoints",
+		Long:    "Show git-blame-style line attribution enriched with Entire checkpoint metadata.\n\nLimit to a line or range with <file>:12, <file>:12-20, or the --line flag.",
+		Example: "  entire blame src/auth.go\n  entire blame src/auth.go:10-40 --json",
+		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runAttributionBlame(cmd.Context(), cmd.OutOrStdout(), args[0], attributionBlameOptions{
 				LineFlag: lineFlag,
@@ -177,10 +178,11 @@ func newWhyCmd() *cobra.Command {
 		// Hidden from `entire help` while the feature is still maturing —
 		// advertised under `entire labs`, and `entire why` / `entire why
 		// --help` keep working normally.
-		Hidden: true,
-		Short:  "Show why a line exists",
-		Long:   "Explain the commit, checkpoint, prompt, and session behind a file or line.\n\nTarget a specific line with <file>:12 or the --line flag.",
-		Args:   cobra.ExactArgs(1),
+		Hidden:  true,
+		Short:   "Show why a line exists",
+		Long:    "Explain the commit, checkpoint, prompt, and session behind a file or line.\n\nTarget a specific line with <file>:12 or the --line flag.",
+		Example: "  entire why src/auth.go:42\n  entire why src/auth.go:42 --json",
+		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runAttributionWhy(cmd.Context(), cmd.OutOrStdout(), args[0], attributionWhyOptions{
 				LineFlag: lineFlag,

cmd/entire/cli/checkpoint_group.go

@@ -50,6 +50,9 @@ Examples:
 func newCheckpointSearchCmd() *cobra.Command {
 	cmd := newSearchCmd()
 	cmd.Hidden = false
+	// newSearchCmd's examples use the `entire search` prefix for that top-level
+	// alias; under the canonical `checkpoint` group they must match this path.
+	cmd.Example = "  entire checkpoint search \"retry backoff\" --json\n  entire checkpoint search \"auth timeout author:alice date:week\"\n  entire checkpoint search --code \"parseToken\""
 	return cmd
 }
 

cmd/entire/cli/checkpoint_tokens.go

@@ -84,7 +84,8 @@ from the checkpoint remote.
 
 Use --compare <checkpoint-id> to compare this checkpoint against a previous
 checkpoint and qualify observed token reduction or increase.`,
-		Args: cobra.ExactArgs(1),
+		Example: "  entire checkpoint tokens a1b2\n  entire checkpoint tokens a1b2 --compare c3d4\n  entire checkpoint tokens a1b2 --json",
+		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if jsonFlag && agentBriefFlag {
 				return errors.New("--json and --agent-brief are mutually exclusive")

cmd/entire/cli/experts_cmd.go

@@ -182,10 +182,18 @@ func (s expertsStyles) link(style lipgloss.Style, url, text string) string {
 func newExpertsCmd() *cobra.Command {
 	f := &expertsFlags{limit: 8}
 	cmd := &cobra.Command{
-		Use:    "experts [scope-or-query]",
-		Short:  "Rank agent provenance for code scopes",
-		Hidden: true,
-		Args:   cobra.ArbitraryArgs,
+		Use:   "experts [scope-or-query]",
+		Short: "Rank agent provenance for code scopes",
+		Long: `Rank which agents, skills, and tools have provenance over a code scope — who
+and what has touched the given code.
+
+The argument is either a single scope (a file or directory path) or a
+natural-language query. A scope or query is required unless --staged is set,
+which uses the staged file paths as scopes instead. Results come from the
+entire-api cell keyed on the repo, so the repo must be mirrored.`,
+		Example: "  entire experts src/payments --json\n  entire experts \"who owns token refresh\" --json\n  entire experts --staged",
+		Hidden:  true,
+		Args:    cobra.ArbitraryArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runExperts(cmd.Context(), cmd.OutOrStdout(), cmd.ErrOrStderr(), args, f)
 		},

cmd/entire/cli/lifecycle.go

@@ -416,20 +416,24 @@ func normalizeToolUsePaths(files []string, eventCWD, repoRoot string) []string {
 // handleLifecycleTurnStart handles turn start: captures pre-prompt state,
 // ensures strategy setup, initializes session.
 // entireTrailContextInjection is the one-time, model-facing pointer Entire
-// injects on the first turn of a session. It deliberately enumerates NO flags or
-// subcommands — that surface is fetched on demand via `entire agent-help`, which
-// always matches the installed CLI — so the injection never goes stale when the
-// command surface grows. It names the auto-detected repo (from the already-loaded
-// session scope, no IO) and carries the standing rule that the agent is inside
-// the repo and must never ask the user for the repo name. Kept terse: it costs
-// context-window tokens on the first turn of every session.
+// injects on the first turn of a session. It points at `entire agent-help` for
+// the full flag/subcommand surface — fetched on demand so that surface never goes
+// stale here as it grows — and adds only a small, stable behavioral invariant an
+// agent must know even if it never drills in: commits auto-capture checkpoints,
+// the two stable query anchors (`why`, `checkpoint search`) for recovering intent
+// before edits, and that setup/destructive commands belong to the user. It also
+// names the auto-detected repo (from the already-loaded session scope, no IO) and
+// the standing rule that the agent is inside the repo and must never ask the user
+// for the repo name. Kept terse: it costs context-window tokens on the first turn
+// of every session.
 func entireTrailContextInjection(scope trailEnablementScope) string {
 	repo := ""
 	if scope.Forge != "" && scope.Owner != "" && scope.Repo != "" {
 		repo = trailEnablementRepoKey(scope.Forge, scope.Owner, scope.Repo)
 	}
 	var b strings.Builder
 	b.WriteString("Entire is enabled for this repo. Run `entire agent-help` to see what entire does and which subcommand to use, then `entire agent-help <command>` for that command's exact, current flags. ")
+	b.WriteString("Commits automatically capture the AI session as a checkpoint, so never create checkpoints by hand — just commit normally. Before large edits, `entire why <file>:<line>` and `entire checkpoint search` recover the intent behind existing code. Leave setup and destructive commands (enable, disable, clean, rewind, auth) to the user. ")
 	// Mirror agentHelpRepoBlock's defense-in-depth: this string is injected raw
 	// into the agent's model context (no escaping), so a repo key carrying control
 	// characters (e.g. an <sessionID>.trail-scope.json cache written by a pre-fix

cmd/entire/cli/search_cmd.go

@@ -55,8 +55,9 @@ displayed in an interactive table. Use --json for machine-readable output.
 
 CLI queries also support inline filters like author:<name>, date:<week|month>,
 branch:<name>, repo:<owner/name>, and repo:* to search all accessible repos.`,
-		Args:   cobra.ArbitraryArgs,
-		Hidden: true,
+		Example: "  entire search \"retry backoff\" --json\n  entire search \"auth timeout author:alice date:week\"\n  entire search --code \"parseToken\"",
+		Args:    cobra.ArbitraryArgs,
+		Hidden:  true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 			query := strings.Join(args, " ")

cmd/entire/cli/search_cmd_test.go

@@ -42,6 +42,23 @@ func TestSearchCmd_AccessibleModeRequiresQuery(t *testing.T) {
 	}
 }
 
+// Each instance's examples must use its own command path: the top-level alias
+// is `entire search`, the canonical form under the checkpoint group is
+// `entire checkpoint search`. A shared prefix would mislead one command's help.
+func TestSearchCmd_ExamplesMatchCommandPath(t *testing.T) {
+	t.Parallel()
+
+	topLevel := newSearchCmd().Example
+	if !strings.Contains(topLevel, "entire search ") || strings.Contains(topLevel, "checkpoint search") {
+		t.Fatalf("top-level search examples must use the `entire search` prefix:\n%s", topLevel)
+	}
+
+	checkpoint := newCheckpointSearchCmd().Example
+	if !strings.Contains(checkpoint, "entire checkpoint search ") {
+		t.Fatalf("checkpoint search examples must use the `entire checkpoint search` prefix:\n%s", checkpoint)
+	}
+}
+
 func TestSearchCmd_HelpMentionsRepoFlagAndInlineFilters(t *testing.T) {
 	t.Parallel()
 

cmd/entire/cli/session_tokens.go

@@ -95,7 +95,8 @@ already captured for the session.
 Use --agent-brief when an agent needs compact guidance for the next step, for
 example: "Use Entire token tracking to check how this session is doing and
 optimize next steps."`,
-		Args: cobra.MaximumNArgs(1),
+		Example: "  entire session tokens\n  entire session tokens --current --agent-brief\n  entire session tokens --json",
+		Args:    cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if jsonFlag && agentBriefFlag {
 				return errors.New("--json and --agent-brief are mutually exclusive")