feat(env): audit events, update cmd, secret redaction, richer plan

Address pre-push review findings before opening PR for #53.

Secret hygiene (Legal HIGH):
- env get redacts env values by default; --reveal unredacts and emits
  environment.revealed audit event
- values files continue to accept env overrides but their raw contents never
  leave the CLI without explicit reveal

Audit coverage (Legal HIGH):
- new audit actions: environment.{created,updated,deleted,revealed}
- Store.Create/Update/Delete emit inside the same tx as the write
- Store gains Actor field (defaults to "cli") to attribute events

User-visible gaps (PM):
- add mantle env update subcommand + Store.Update that preserves id and
  created_at so environment history isn't lost on edits
- plan --env now appends a "Resolved configuration" block showing final
  inputs and env vars with the layer each value came from
- env delete requires --yes/-y; refuses to proceed without it
- env get shows created/updated timestamps and env IDs
- rename env show to env get to match kubectl/gh conventions
- relax name regex to ^[a-z0-9][a-z0-9_-]* so production, prod_1, env-v2,
  123env all validate

Polish (Tech Writer + Reality Checker):
- richer Long/Example text across all env subcommands
- migration 018 gains header comment explaining purpose and reveal contract
- cel.SetValuesEnv godoc reflects that both values and named envs feed it
- replace err == sql.ErrNoRows with errors.Is throughout environment store
- ErrNotFound sentinel for Get/Update/Delete misses

Docs:
- CLAUDE.md Key Commands lists mantle env and --values/--env flags with the
  full override precedence chain

Tests: extend store_test with Update, ValidNameRelaxed, InvalidName (broader
cases), AuditEvents; add plan_test for writeResolvedOverrides source
attribution.

Author: michaelmcnees

CLAUDE.md

@@ -75,9 +75,20 @@ mantle logs <execution-id>    # View execution logs
 mantle status <execution-id>  # View execution state
 mantle secrets create         # Create typed credential
 mantle secrets rotate-key     # Re-encrypt credentials with new key
+mantle env create <name>      # Create a named environment from a values file
+mantle env update <name>      # Replace inputs/env on an existing environment
+mantle env list               # List named environments
+mantle env get <name>         # Show environment details (env values redacted; --reveal to unredact, audited)
+mantle env delete <name> -y   # Delete a named environment (requires --yes)
+mantle run <wf> --values f.yaml   # Run with a values file (inputs + env overrides)
+mantle run <wf> --env <name>      # Run against a stored named environment
+mantle plan <wf> --env <name>     # Plan; appends resolved inputs/env with source
 mantle serve                  # Start persistent server
 ```
 
+**Override precedence (highest wins):**
+`MANTLE_ENV_*` OS vars > `--input` flags > `--values` file > `--env` named environment > workflow `default` values > config `env:` section
+
 ## License
 
 BSL/SSPL-style — source available, no commercial resale of forks.

packages/engine/internal/audit/audit.go

@@ -55,6 +55,12 @@ const (
 
 	// Rollback operations.
 	ActionWorkflowRolledBack Action = "workflow.rolled_back"
+
+	// Environment operations.
+	ActionEnvironmentCreated  Action = "environment.created"
+	ActionEnvironmentUpdated  Action = "environment.updated"
+	ActionEnvironmentDeleted  Action = "environment.deleted"
+	ActionEnvironmentRevealed Action = "environment.revealed"
 )
 
 // Resource identifies the target of an audit event.

packages/engine/internal/cel/cel.go

@@ -233,9 +233,10 @@ func (e *Evaluator) SetConfigEnv(configEnv map[string]string) {
 	e.envCache = mergeEnvVars(configEnv, e.valuesEnv)
 }
 
-// SetValuesEnv sets the values-file env overrides and rebuilds the env cache.
-// Values-file env sits between config env and MANTLE_ENV_* OS variables in
-// the precedence stack: config < values < MANTLE_ENV_*.
+// SetValuesEnv sets the values-file and named-environment env overrides
+// and rebuilds the env cache. Overlays them on top of config env; MANTLE_ENV_*
+// OS vars still win. The layered precedence is config < values/named-env <
+// MANTLE_ENV_*.
 func (e *Evaluator) SetValuesEnv(valuesEnv map[string]string) {
 	e.valuesEnv = valuesEnv
 	e.envCache = mergeEnvVars(e.configEnv, e.valuesEnv)

packages/engine/internal/cli/env.go

@@ -12,17 +12,30 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// redactedPlaceholder is printed in place of env values in `env get` output
+// unless --reveal is passed. Values files commonly contain secret-shaped
+// material (API keys, connection strings, tokens) and must not leak to logs
+// or terminal scrollback by default. Revealing is always audited.
+const redactedPlaceholder = "<redacted>"
+
 // newEnvCommand returns the "env" subcommand for managing named environments.
 func newEnvCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "env",
 		Short: "Manage named environments",
-		Long:  "Create, list, show, and delete named environments for parameterized workflow execution.",
+		Long: `Named environments (e.g., "production", "staging") store reusable input
+and env variable sets for parameterized workflow runs. Combine with
+` + "`mantle run --env <name>`" + ` and ` + "`mantle plan --env <name>`" + ` to promote the
+same workflow across environments without rewriting CLI flags.
+
+Override precedence (highest wins):
+  --input flags > --values file > --env named environment > workflow defaults`,
 	}
 
 	cmd.AddCommand(newEnvCreateCommand())
+	cmd.AddCommand(newEnvUpdateCommand())
 	cmd.AddCommand(newEnvListCommand())
-	cmd.AddCommand(newEnvShowCommand())
+	cmd.AddCommand(newEnvGetCommand())
 	cmd.AddCommand(newEnvDeleteCommand())
 
 	return cmd
@@ -36,31 +49,39 @@ func newEnvCreateCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create <name>",
 		Short: "Create a named environment",
-		Long:  "Creates a named environment from a values file.",
+		Long: `Creates a named environment from a YAML values file. The file must
+contain top-level ` + "`inputs:`" + ` and/or ` + "`env:`" + ` keys. Names must match
+[a-z0-9][a-z0-9_-]*. Fails if an environment with the same name already
+exists in the team scope; use ` + "`mantle env update`" + ` to replace it.`,
 		Example: `  mantle env create production --from prod.values.yaml
   mantle env create staging --from staging.values.yaml`,
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			name := args[0]
+			return runEnvWrite(cmd, args[0], fromFile, writeModeCreate)
+		},
+	}
 
-			vals, err := workflow.LoadValues(fromFile)
-			if err != nil {
-				return fmt.Errorf("loading values file: %w", err)
-			}
+	cmd.Flags().StringVar(&fromFile, "from", "", "Values file to load inputs and env from (required)")
+	_ = cmd.MarkFlagRequired("from")
 
-			store, cleanup, err := newEnvStore(cmd)
-			if err != nil {
-				return err
-			}
-			defer cleanup()
+	return cmd
+}
 
-			env, err := store.Create(cmd.Context(), name, vals.Inputs, vals.Env)
-			if err != nil {
-				return err
-			}
+// newEnvUpdateCommand returns the "env update" subcommand, which replaces the
+// stored inputs and env on an existing named environment.
+func newEnvUpdateCommand() *cobra.Command {
+	var fromFile string
 
-			fmt.Fprintf(cmd.OutOrStdout(), "Created environment %q\n", env.Name)
-			return nil
+	cmd := &cobra.Command{
+		Use:   "update <name>",
+		Short: "Update an existing named environment",
+		Long: `Replaces the inputs and env of an existing environment with the contents
+of a values file. Preserves the environment ID, creation timestamp, and audit
+history. Fails if the environment does not exist.`,
+		Example: `  mantle env update production --from prod.values.yaml`,
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runEnvWrite(cmd, args[0], fromFile, writeModeUpdate)
 		},
 	}
 
@@ -70,13 +91,56 @@ func newEnvCreateCommand() *cobra.Command {
 	return cmd
 }
 
+type envWriteMode int
+
+const (
+	writeModeCreate envWriteMode = iota
+	writeModeUpdate
+)
+
+// runEnvWrite is the shared body for create/update: load a values file,
+// dispatch to the matching Store method, and print a single-line confirmation.
+func runEnvWrite(cmd *cobra.Command, name, fromFile string, mode envWriteMode) error {
+	vals, err := workflow.LoadValues(fromFile)
+	if err != nil {
+		return fmt.Errorf("loading values file: %w", err)
+	}
+
+	store, cleanup, err := newEnvStore(cmd)
+	if err != nil {
+		return err
+	}
+	defer cleanup()
+
+	var e *environment.Environment
+	var verb string
+	switch mode {
+	case writeModeCreate:
+		e, err = store.Create(cmd.Context(), name, vals.Inputs, vals.Env)
+		verb = "Created"
+	case writeModeUpdate:
+		e, err = store.Update(cmd.Context(), name, vals.Inputs, vals.Env)
+		verb = "Updated"
+	}
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(cmd.OutOrStdout(), "%s environment %q\n", verb, e.Name)
+	return nil
+}
+
 // newEnvListCommand returns the "env list" subcommand, which prints all named
-// environments for the current team.
+// environments for the current team with their creation and update timestamps.
 func newEnvListCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:   "list",
-		Short: "List all environments",
-		Args:  cobra.NoArgs,
+		Short: "List all named environments",
+		Long: `Lists every environment in the current team scope with creation and
+update timestamps. Raw input and env values are never shown here — use
+` + "`mantle env get <name> --reveal`" + ` to view them.`,
+		Example: `  mantle env list`,
+		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			store, cleanup, err := newEnvStore(cmd)
 			if err != nil {
@@ -95,22 +159,35 @@ func newEnvListCommand() *cobra.Command {
 			}
 
 			w := tabwriter.NewWriter(cmd.OutOrStdout(), 0, 0, 2, ' ', 0)
-			fmt.Fprintln(w, "NAME\tCREATED")
+			fmt.Fprintln(w, "NAME\tCREATED\tUPDATED")
 			for _, e := range envs {
-				fmt.Fprintf(w, "%s\t%s\n", e.Name, e.CreatedAt.UTC().Format("2006-01-02 15:04:05 UTC"))
+				fmt.Fprintf(w, "%s\t%s\t%s\n",
+					e.Name,
+					e.CreatedAt.UTC().Format("2006-01-02 15:04:05 UTC"),
+					e.UpdatedAt.UTC().Format("2006-01-02 15:04:05 UTC"),
+				)
 			}
 			return w.Flush()
 		},
 	}
 }
 
-// newEnvShowCommand returns the "env show" subcommand, which prints the inputs
-// and env vars stored in a named environment.
-func newEnvShowCommand() *cobra.Command {
-	return &cobra.Command{
-		Use:   "show <name>",
+// newEnvGetCommand returns the "env get" subcommand, which prints the stored
+// inputs and env for a named environment. Env values are redacted unless the
+// caller passes --reveal, which emits an environment.revealed audit event.
+func newEnvGetCommand() *cobra.Command {
+	var reveal bool
+
+	cmd := &cobra.Command{
+		Use:   "get <name>",
 		Short: "Show environment details",
-		Args:  cobra.ExactArgs(1),
+		Long: `Shows the stored inputs and env for a named environment along with its
+timestamps. Env values are redacted by default because values files often
+contain secret-shaped material. Pass --reveal to print raw values; every
+reveal emits an ` + "`environment.revealed`" + ` audit event.`,
+		Example: `  mantle env get production
+  mantle env get production --reveal`,
+		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			store, cleanup, err := newEnvStore(cmd)
 			if err != nil {
@@ -123,42 +200,63 @@ func newEnvShowCommand() *cobra.Command {
 				return err
 			}
 
-			fmt.Fprintf(cmd.OutOrStdout(), "Name: %s\n", env.Name)
-			if len(env.Inputs) > 0 {
-				fmt.Fprintln(cmd.OutOrStdout(), "\nInputs:")
-				keys := make([]string, 0, len(env.Inputs))
-				for k := range env.Inputs {
-					keys = append(keys, k)
+			if reveal {
+				if revealErr := store.EmitReveal(cmd.Context(), env); revealErr != nil {
+					return fmt.Errorf("recording reveal audit event: %w", revealErr)
 				}
-				sort.Strings(keys)
-				for _, k := range keys {
-					fmt.Fprintf(cmd.OutOrStdout(), "  %s: %v\n", k, env.Inputs[k])
+			}
+
+			out := cmd.OutOrStdout()
+			fmt.Fprintf(out, "Name:       %s\n", env.Name)
+			fmt.Fprintf(out, "ID:         %s\n", env.ID)
+			fmt.Fprintf(out, "Created:    %s\n", env.CreatedAt.UTC().Format("2006-01-02 15:04:05 UTC"))
+			fmt.Fprintf(out, "Updated:    %s\n", env.UpdatedAt.UTC().Format("2006-01-02 15:04:05 UTC"))
+
+			if len(env.Inputs) > 0 {
+				fmt.Fprintln(out, "\nInputs:")
+				for _, k := range sortedKeys(env.Inputs) {
+					fmt.Fprintf(out, "  %s: %v\n", k, env.Inputs[k])
 				}
 			}
 			if len(env.Env) > 0 {
-				fmt.Fprintln(cmd.OutOrStdout(), "\nEnv:")
-				keys := make([]string, 0, len(env.Env))
-				for k := range env.Env {
-					keys = append(keys, k)
+				fmt.Fprintln(out, "\nEnv:")
+				for _, k := range sortedStringKeys(env.Env) {
+					if reveal {
+						fmt.Fprintf(out, "  %s: %s\n", k, env.Env[k])
+					} else {
+						fmt.Fprintf(out, "  %s: %s\n", k, redactedPlaceholder)
+					}
 				}
-				sort.Strings(keys)
-				for _, k := range keys {
-					fmt.Fprintf(cmd.OutOrStdout(), "  %s: %s\n", k, env.Env[k])
+				if !reveal {
+					fmt.Fprintln(out, "\n(Env values redacted. Pass --reveal to display; reveals are audited.)")
 				}
 			}
 			return nil
 		},
 	}
+
+	cmd.Flags().BoolVar(&reveal, "reveal", false, "Print raw env values (emits an environment.revealed audit event)")
+	return cmd
 }
 
-// newEnvDeleteCommand returns the "env delete" subcommand, which removes a
-// named environment from the database.
+// newEnvDeleteCommand returns the "env delete" subcommand, which permanently
+// removes a named environment. Requires --yes to confirm.
 func newEnvDeleteCommand() *cobra.Command {
-	return &cobra.Command{
+	var yes bool
+
+	cmd := &cobra.Command{
 		Use:   "delete <name>",
 		Short: "Delete an environment",
-		Args:  cobra.ExactArgs(1),
+		Long: `Permanently deletes a named environment. Requires --yes to confirm
+because deletion cannot be undone from the CLI — referring workflow runs will
+fail until the environment is recreated.`,
+		Example: `  mantle env delete staging --yes`,
+		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			if !yes {
+				return fmt.Errorf("refusing to delete %q without --yes", args[0])
+			}
+
 			store, cleanup, err := newEnvStore(cmd)
 			if err != nil {
 				return err
@@ -173,6 +271,9 @@ func newEnvDeleteCommand() *cobra.Command {
 			return nil
 		},
 	}
+
+	cmd.Flags().BoolVarP(&yes, "yes", "y", false, "Confirm deletion (required)")
+	return cmd
 }
 
 // newEnvStore builds an environment.Store from the current command context.
@@ -187,7 +288,29 @@ func newEnvStore(cmd *cobra.Command) (*environment.Store, func(), error) {
 		return nil, nil, fmt.Errorf("failed to connect to database: %w", err)
 	}
 
-	store := &environment.Store{DB: database}
+	store := &environment.Store{DB: database, Actor: "cli"}
 	cleanup := func() { database.Close() }
 	return store, cleanup, nil
 }
+
+// sortedKeys returns the keys of m in ascending order. Used for deterministic
+// output in env get.
+func sortedKeys(m map[string]any) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// sortedStringKeys returns the keys of m in ascending order. Used for
+// deterministic output in env get.
+func sortedStringKeys(m map[string]string) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}