Clarify that bare `kanon import` is preview-only and writes nothing

[kelos-bot]

When I tried the first-run flow in a fresh home, kanon import without --write did not import into kanon.yaml; it printed the normalized config to stdout instead, along with warnings about skipped fields.

Repro:

1. kanon init --home /tmp/kanon-home
2. kanon import --home /tmp/kanon-home --agent all

Observed:

• stdout contains YAML for the imported config
• warnings are emitted for skipped/secret fields
• nothing is written to the Kanon home unless --write is added

Why this is confusing:

• the command name reads like a write operation
• import --help documents --write, but does not say that bare import is preview-only
• the README examples focus on --ui and --write, so a user who tries the plain command may think it failed or is interactive

Suggestion:

• add an explicit note to kanon import --help and the README that bare kanon import is a non-writing preview that prints the normalized source to stdout
• optionally include a short example showing kanon import --write as the default way to persist the result

[kelos-bot]

🤖 Kelos Task Status

Task kanon-triage-issues-8017a73a0e4e has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kanon Triage Report

Kind: kind/docs
Priority: priority/important-longterm — This is a user-facing documentation/help clarity issue, but the command behavior is intentional and not blocking.
Actor: actor/kelos — The scope is a focused README and CLI help text clarification with objectively verifiable output.

Status: STILL VALID

Evidence:

• No merged PRs referencing Clarify that bare kanon import is preview-only and writes nothing #55 were found with gh pr list --state merged --search "55" --limit 50.
• No recent commits were found with git log --oneline -50 --grep="55" or the import/preview keyword grep.
• Current CLI code writes only when --write is set, otherwise it calls ImportPreview and prints YAML to stdout:

  kanon/internal/cli/root.go

  Lines 224 to 235 in 3edde45

  	if opts.write {
  	if err := core.WriteImport(target.KanonHome, result, opts.force); err != nil {
  	return err
  	}
  	fmt.Fprintf(cmd.OutOrStdout(), "Wrote imported config to %s\n", filepath.Join(target.KanonHome, "kanon.yaml"))
  	return nil
  	}
  	data, err := core.ImportPreview(result)
  	if err != nil {
  	return err
  	}
  	fmt.Fprint(cmd.OutOrStdout(), string(data))

• WriteImport is the only path that writes kanon.yaml and imported files, while ImportPreview only marshals the normalized config:

  kanon/internal/core/import.go

  Lines 70 to 90 in 3edde45

  	func WriteImport(home string, result *ImportResult, force bool) error {
  	configPath := filepath.Join(home, "kanon.yaml")
  	if _, err := os.Stat(configPath); err == nil && !force {
  	return fmt.Errorf("%s already exists; re-run import with --force to replace it", configPath)
  	} else if err != nil && !errors.Is(err, os.ErrNotExist) {
  	return err
  	}
  	for rel, data := range result.Files {
  	path := ResolvePath(home, rel)
  	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
  	return err
  	}
  	if err := os.WriteFile(path, data, 0o644); err != nil {
  	return err
  	}
  	}
  	return WriteConfig(configPath, result.Config)
  	}
  	func ImportPreview(result *ImportResult) ([]byte, error) {
  	return configToYAML(result.Config)

• go run . import --help documents --write but does not explicitly state that bare kanon import is preview-only.
• The README import section mentions --ui and says to use --write for scripted imports, but does not explicitly call out bare kanon import as a non-writing stdout preview:

  kanon/README.md

  Lines 156 to 174 in 3edde45

  	## Importing existing settings
  	```sh
  	kanon import --ui
  	kanon import --agent all --ui
  	kanon import --agent all --write
  	kanon import --agent all --write --force
  	```
  	`import` runs the pipeline in reverse: it reads existing Codex and Claude files
  	(the destination state) and normalizes them back into the neutral source state.
  	For interactive use, prefer `kanon import --ui`: it reviews discovered
  	instructions, skills, MCP servers, and hooks as selectable import units before
  	writing them into the source. The same import review is available from
  	`kanon ui`; press `m` to switch between apply and import modes, or start there
  	with `kanon ui --mode import`.
  	Use `--write` for scripted imports that should write the full normalized result
  	without interactive review.

Duplicates found: None found

Recommendation: KEEP OPEN