@calcit/procs 0.12.35 → 0.12.36

package/README.md

@@ -12,11 +12,17 @@ Core design:
 
 - Interpreter runs on Rust, extensible with Rust FFI
 - Persistent Data Structure
-- Structural Editor(with indentation-based syntax as a fallback)
+- Indentation-based Cirru syntax, friendly to plain text editing
 - Lisp macros, functional style
 - Compiles to JavaScript in ES Modules, JavaScript Interop
 - Hot code swapping friendly
 
+Current direction:
+
+- `calcit.cirru` is the primary source snapshot; legacy `compact.cirru` is still compatible
+- CLI-first development with `cr` and `caps`, designed to work well with AI agents in terminal workflows
+- Better CLI editing and validation for CI, docs lookup, module management, and incremental updates
+
 ### Install ![GitHub Release](https://img.shields.io/github/v/release/calcit-lang/calcit)
 
 Build and install with Rust:
@@ -29,12 +35,12 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 cargo install calcit
 ```
 
-4 binaries are installed:
+Installed binaries:
 
 - `calcit`, the runtime and js compiler
 - `cr-wasm`, standalone WASM codegen tool
 - `caps`, for downloading dependencies declared in `deps.cirru`
-- `bundle_calcit`, bundle code if you don't want to use Calcit Editor
+- `bundle_calcit`, bundle code for distribution
 
 When installing from source, explicitly include both runners:
 
@@ -44,9 +50,9 @@ cargo install --path . --bin cr --bin cr-wasm --bin caps --bin bundle_calcit
 
 To use Calcit in GitHub Actions, try [setup-cr](https://github.com/calcit-lang/setup-cr).
 
-### Usage
+### Quick Start
 
-Snippets evaluating:
+Evaluate snippets:
 
 ```bash
 cr eval 'range 100'
@@ -54,7 +60,7 @@ cr eval 'range 100'
 cr eval 'thread-first 100 range (map $ \ * % %)'
 ```
 
-Run with a runtime snapshot such as [calcit.cirru](https://github.com/calcit-lang/lilac/blob/main/compact.cirru) (legacy filename: `compact.cirru`):
+Run with a runtime snapshot such as `calcit.cirru` (legacy filename: `compact.cirru`):
 
 ```bash
 cr calcit.cirru # run once (default)
@@ -65,13 +71,13 @@ cr # by default, it picks `calcit.cirru`, then falls back to `compact.cirru`
 cr -w # watch mode (explicit flag required)
 ```
 
-By default Calcit reads `:init-fn` and `:reload-fn` inside `calcit.cirru` configs (falling back to `compact.cirru`). You may also specify functions,
+By default Calcit reads `:init-fn` and `:reload-fn` from `calcit.cirru` configs (falling back to `compact.cirru`). You may also specify functions:
 
 ```bash
 cr --init-fn='app.main/main!' --reload-fn='app.main/reload!'
 ```
 
-and even configure `:entries` in `calcit.cirru`:
+You may also configure `:entries` in `calcit.cirru`:
 
 ```bash
 cr --entry server
@@ -79,7 +85,7 @@ cr --entry server
 
 ### JavaScript codegen
 
-It compiles to JavaScript and runs in consistet semantics. However it might require a lot of JavaScript interop.
+Calcit compiles to JavaScript with consistent semantics. In browser or Node projects, JavaScript interop is still expected.
 
 ```bash
 cr js # compile to js, also picks `calcit.cirru` by default
@@ -93,40 +99,28 @@ import { main_$x_, reload_$x_ } from "./js-out/app.main.mjs";
 main_$x_(); // which corresponds to `main!` function in calcit
 ```
 
-### Calcit Editor & Bundler
-
-Install [Calcit Editor](https://github.com/calcit-lang/editor) and run `ct` to launch editor server,
-which writes `calcit.cirru` and `.compact-inc.cirru` on saving. Legacy `compact.cirru` remains compatible. Try launching example by cloning [Calcit Workflow](https://github.com/calcit-lang/calcit-workflow).
-
-Read more in [Minimal Calcit](https://github.com/calcit-lang/minimal-calcit/blob/main/README.md) to learn how to code Calcit with a plain text editor.
-
-Read more in [Respo Calcit Workflow](https://github.com/calcit-lang/respo-calcit-workflow) to learn to create an MVC webpage with [Respo](http://respo-mvc.org/).
-
-### MCP (Model Context Protocol) Support
-
-Calcit provides MCP server functionality for integration with AI assistants and development tools. The MCP server offers tools for:
+### CLI and Agent Workflow
 
-- **Code Management**: Read, write, and modify Calcit namespaces and definitions
-- **Project Operations**: Manage modules, dependencies, and configurations
-- **Calcit Runner**: Start/stop background runner processes with incremental updates
-- **Documentation**: Query API docs, reference materials, and dependency documentation
+The recommended workflow is plain text editing plus CLI validation, often driven by an AI agent in terminal.
 
-#### Incremental File Processing
+Common commands:
 
-When using the Calcit Runner through MCP:
-
-1. **Start Runner**: Use `start_calcit_runner` to launch the background process. This automatically:
-   - Creates a `.calcit-tmp/` directory
-   - Copies the current runtime snapshot (`calcit.cirru`, or legacy `compact.cirru`) as a temporary baseline
+```bash
+cr docs agents --full   # read the current agent workflow guide
+cr query search 'foo'   # locate code by symbol or string
+cr edit ...             # structured edits for defs, imports, config, modules
+cr js                   # compile once
+cr js -w                # watch mode
+caps                    # install/update dependencies from deps.cirru
+```
 
-2. **Generate Incremental Updates**: After making changes to your code, use `generate_calcit_incremental` to:
-   - Compare current runtime snapshot with the temporary baseline
-   - Generate a `.compact-inc.cirru` file with only the changes
-   - Apply incremental updates to the running process
+Calcit Editor is no longer the recommended path for everyday development. If you still need the older editor workflow, see [Calcit Editor](https://github.com/calcit-lang/editor).
 
-3. **Check Results**: After generating the incremental file, always check the runner logs using `grab_calcit_runner_logs` to verify that updates were applied successfully.
+Related examples and workflows:
 
-This workflow enables efficient hot-reloading during development without restarting the entire application.
+- [Minimal Calcit](https://github.com/calcit-lang/minimal-calcit/blob/main/README.md)
+- [Respo Calcit Workflow](https://github.com/calcit-lang/respo-calcit-workflow)
+- [setup-cr](https://github.com/calcit-lang/setup-cr) for GitHub Actions
 
 ### Modules
 
@@ -142,7 +136,7 @@ This workflow enables efficient hot-reloading during development without restart
 
 Run `caps` to download. Sources are downloaded into `~/.config/calcit/modules/`. If a module contains `build.sh`, it will be executed mostly for compiling Rust dylibs.
 
-`:calcit-version` helps in check version, and provides hints in [CI](https://github.com/calcit-lang/setup-cr) environment.
+`:calcit-version` helps with version checks and provides hints in [CI](https://github.com/calcit-lang/setup-cr).
 
 To load modules, use `:modules` configuration and the runtime snapshot file `calcit.cirru` (legacy: `compact.cirru`):
 
@@ -154,11 +148,11 @@ To load modules, use `:modules` configuration and the runtime snapshot file `cal
 Paths defined in `:modules` field are just loaded as files from `~/.config/calcit/modules/`,
 i.e. `~/.config/calcit/modules/memof/calcit.cirru`.
 
-Modules that ends with `/`s are automatically suffixed `calcit.cirru`, and still fall back to `compact.cirru` for compatibility.
+Modules ending with `/` are automatically suffixed with `calcit.cirru`, and still fall back to `compact.cirru` for compatibility.
 
 ### Development
 
-I use these commands to run local examples:
+Local validation commands:
 
 ```bash
 # run tests in Rust
@@ -175,6 +169,16 @@ cr calcit.cirru ir # compiles intermediate representation into program-ir.cirru
 cr-wasm calcit/test-wasm.cirru # compile standalone wasm target to js-out/program.wasm
 ```
 
+For repository development, the usual validation flow is:
+
+```bash
+cargo fmt
+cargo clippy -- -D warnings
+yarn compile
+cargo test
+yarn check-all
+```
+
 - [Cirru Parser](https://github.com/Cirru/parser.rs) for indentation-based syntax parsing.
 - [Cirru EDN](https://github.com/Cirru/cirru-edn.rs) for runtime snapshot file parsing (`calcit.cirru` / legacy `compact.cirru`).
 - [Ternary Tree](https://github.com/calcit-lang/ternary-tree.rs) for immutable list data structure.

package/{rfc → RFCs}/03-05-function-schema-dual-track-rfc.md

@@ -28,8 +28,8 @@
       :args $ [] 'T :number
       :rest :number
       :return $ :: :tuple :ok 'U
-      :where $ []
-        :: 'Eq 'T
+      :where $ {}
+        'T Eq
 ```
 
 说明：
@@ -83,20 +83,19 @@
 
 ## `:where` 约束
 
-约束统一放在 `:where`，每条约束是一条 tuple：
+约束统一放在 `:where` map，key 是泛型变量，value 是单个 trait 或 trait 列表：
 
 ```cirru
-[]
-  :: 'Eq 'T
-  :: 'Show 'T
-  :: 'Ord 'U
+{}
+  'T $ [] Eq Show
+  'U Ord
 ```
 
 约定：
 
-- 同一变量多条约束表示“且”；
-- 顺序不影响语义；
-- 若当前没有约束，直接写 `:where $ []`。
+- 同一变量多个约束放在同一个 value 列表里，表示“且”；
+- map 项顺序不影响语义；
+- 若当前没有约束，直接省略 `:where`，或写空 map `:where $ {}`。
 
 ## parse 校验示例
 
@@ -105,13 +104,13 @@
 主示例：
 
 ```bash
-cr demos/calcit.cirru cirru parse-edn "(:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T)))))"
+cr demos/calcit.cirru cirru parse-edn "(:: :fn ({} (:generics ([] 'T 'U)) (:where ({} ('T Eq))) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U))))"
 ```
 
 运行时数据验证：
 
 ```bash
-cr demos/calcit.cirru eval "let ((schema (:: :fn ({} (:generics ([] 'T 'U)) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)) (:where ([] (:: 'Eq 'T))))))) (println schema) (println (type-of schema)) , schema"
+cr demos/calcit.cirru eval "let ((schema (:: :fn ({} (:generics ([] 'T 'U)) (:where ({} ('T Eq))) (:args ([] 'T :number)) (:rest :number) (:return (:: :tuple :ok 'U)))))) (println schema) (println (type-of schema)) , schema"
 ```
 
 ## 顶层定义与局部定义的分工

package/RFCs/05-31-generic-where-bounds-mfs.md

@@ -0,0 +1,124 @@
+# 泛型 `:where` 约束 MFS
+
+日期：2026-05-31
+
+状态：Draft
+
+## 目标
+
+在现有函数 schema 泛型链路上，增加最小可用的 trait 约束能力：
+
+- schema / `hint-fn` 可以声明 `:where`；
+- 调用点在泛型变量完成绑定后，检查绑定结果是否满足 trait 约束；
+- 先走主链路，不引入完整 trait solver，不处理复杂的 transitive requires 推导。
+
+## 当前实现边界
+
+本轮只覆盖：
+
+- `CalcitFnTypeAnnotation` 的 `:where` 解析与序列化；
+- 顶层 `:schema` 注入 `hint-fn` 后，用户函数调用的 `:where` 检查；
+- 局部函数 / 期望函数类型场景的 `:where` 检查；
+- trait 约束当前以 preprocess warning 形式暴露。
+
+本轮不覆盖：
+
+- trait `requires` 的递归满足性；
+- 约束失败直接升级为 hard error；
+- 基于 `:where` 的代码生成优化；
+- 复杂多态分派或 impl 搜索策略调整。
+
+## Canonical Cirru EDN 形态
+
+### 顶层 wrapped schema
+
+`CodeEntry.:schema` 在 snapshot / Cirru EDN 里的推荐形态：
+
+```cirru
+%{} :CodeEntry
+  :doc |demo
+  :code $ quote
+    defn show-it (x)
+      .show x
+  :examples $ []
+  :schema $ :: :fn
+    {}
+      :generics $ [] 'T
+      :where $ {}
+        'T Show
+      :args $ [] 'T
+      :return :string
+```
+
+### 多 trait 约束
+
+单个类型变量绑定多个 trait 时，值是一个列表：
+
+```cirru
+:: :fn $ {}
+  :generics $ [] 'T 'U
+  :where $ {}
+    'T $ [] Show Eq
+    'U Ord
+  :args $ [] 'T 'U
+  :return 'T
+```
+
+### 一行 Cirru EDN 示例
+
+```cirru
+(:: :fn ({} (:generics ([] 'T 'U)) (:where ({} ('T ([] Show Eq)) ('U Ord))) (:args ([] 'T 'U)) (:return 'T)))
+```
+
+## 约束格式结论
+
+`:`where` 当前使用 map，而不是 list-of-tuples。这一点刻意对齐 Rust `where` 的分离式设计：泛型名字继续放在 `:generics`，trait 约束单独放在 `:where`，避免把“变量声明”和“约束条件”混在同一个位置里。
+
+- key: 泛型变量，例如 `'T`
+- value: 单个 trait，或 `[]` 列表中的多个 trait
+
+也就是：
+
+```cirru
+:where $ {}
+  'T Show
+  'U $ [] Eq Ord
+```
+
+不要写成旧草案里的 tuple 形式。`:: 'Show 'T` / `:: 'Eq 'U` 这类写法已经废弃，不应再出现在任何新文档、示例或测试输入里。
+
+后者不要再作为新文档示例。
+
+在概念上可以把它理解成 Rust 里的：
+
+- `fn f<T, U>(...) where T: Show + Eq, U: Ord`
+- 在 Calcit 中对应为 `:generics $ [] 'T 'U` 与 `:where $ {} 'T $ [] Show Eq  'U Ord`
+
+## 与 EDN / 内部表示的关系
+
+- Cirru 文本里写 `'T`；
+- 进入 EDN 后，它仍然是 symbol，只是内部不会把前导 `'` 作为名字的一部分存储；
+- trait 名称在 schema 里直接写定义名，例如 `Show`、`Eq`，不加 `:` 前缀。
+
+## 主链路开发步骤
+
+1. 文档先固定 canonical `:where` 形态，避免继续沿用旧 tuple 草案。
+2. schema parse / serialize 支持 `:where`。
+3. 用户函数与局部函数调用，在泛型绑定后做 trait 约束检查。
+4. 增加 parse / roundtrip / warning 级别测试。
+5. 视结果决定是否把 warning 升级成 error，并是否纳入 trait `requires`。
+
+## 当前测试最小集
+
+至少保留以下方向：
+
+- `hint-fn` 里的 `:where` 能被提取；
+- 顶层 schema roundtrip 后 `:where` 不丢失；
+- 满足 trait 约束时无 warning；
+- 不满足 trait 约束时出现明确 warning。
+
+## 下一步
+
+- 先把 `03-05-function-schema-dual-track-rfc.md` 中旧的 `:where` tuple 示例替换掉；
+- 再补 schema roundtrip 测试，确保文档与实际输出一致；
+- 之后再决定是否把约束失败升级为 `E_GENERIC_WHERE_BOUND_MISMATCH`。

package/{rfc → RFCs}/README.md

@@ -26,6 +26,7 @@
 | `04-15-type-directed-optimization-catalog.md` | Active | 基于 `&record:nth` 经验，系统梳理 Record/Tuple/Scope 等类型导向优化机会。 |
 | `04-15-wasm-compilation-feasibility.md` | Active | WASM 编译三条路径（解释器→WASM / AOT 子集 / WASM GC）的可行性评估。 |
 | `04-16-wasm-data-structures.md` | Active | WASM codegen 中 Tag/Record/Tuple 等数据结构的内存布局与编译策略。 |
+| `05-31-generic-where-bounds-mfs.md` | Active | 函数 schema 泛型 `:where` 约束的最小功能规格，先作为主链路开发基线。 |
 
 ## 已执行的清理
 

package/build.rs

@@ -1,4 +1,4 @@
-use cirru_edn::{Edn, EdnRecordView, from_edn};
+use cirru_edn::{Edn, EdnMapView, EdnRecordView, from_edn};
 use cirru_parser::Cirru;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
@@ -102,6 +102,56 @@ fn map_key_path_segment(key: &Edn) -> String {
   }
 }
 
+fn canonical_schema_field_name(text: &str) -> Option<&'static str> {
+  match text.trim_start_matches(':') {
+    "kind" => Some("kind"),
+    "args" => Some("args"),
+    "return" => Some("return"),
+    "rest" => Some("rest"),
+    "generics" => Some("generics"),
+    "where" => Some("where"),
+    _ => None,
+  }
+}
+
+fn canonical_schema_kind_name(text: &str) -> Option<&'static str> {
+  match text.trim_start_matches(':') {
+    "fn" => Some("fn"),
+    "macro" => Some("macro"),
+    _ => None,
+  }
+}
+
+fn normalize_schema_map(map: &EdnMapView) -> Edn {
+  let mut normalized = EdnMapView::default();
+
+  for (key, value) in &map.0 {
+    let normalized_key = match key {
+      Edn::Tag(tag) => Edn::tag(tag.ref_str()),
+      Edn::Str(text) => canonical_schema_field_name(text.as_ref())
+        .map(Edn::tag)
+        .unwrap_or_else(|| key.clone()),
+      Edn::Symbol(text) => canonical_schema_field_name(text.as_ref())
+        .map(Edn::tag)
+        .unwrap_or_else(|| key.clone()),
+      _ => key.clone(),
+    };
+
+    let normalized_value = match (&normalized_key, value) {
+      (Edn::Tag(tag), Edn::Str(text)) | (Edn::Tag(tag), Edn::Symbol(text)) if tag.ref_str() == "kind" => {
+        canonical_schema_kind_name(text.as_ref())
+          .map(Edn::tag)
+          .unwrap_or_else(|| value.clone())
+      }
+      _ => value.clone(),
+    };
+
+    normalized.insert(normalized_key, normalized_value);
+  }
+
+  Edn::Map(normalized)
+}
+
 /// Convert a schema Edn value (either old Quote-wrapped or new direct map) into Edn map form.
 fn parse_schema_from_edn(value: &Edn, owner: &str) -> Result<Edn, String> {
   // Simple scalar schemas (e.g. :dynamic, :nil) are valid as-is — skip Cirru path
@@ -110,6 +160,29 @@ fn parse_schema_from_edn(value: &Edn, owner: &str) -> Result<Edn, String> {
       validate_schema_edn_no_legacy_quotes(value, owner)?;
       return Ok(value.clone());
     }
+    Edn::Map(map) => {
+      let normalized = normalize_schema_map(map);
+      validate_schema_edn_no_legacy_quotes(&normalized, owner)?;
+      return Ok(normalized);
+    }
+    Edn::Tuple(view)
+      if matches!(view.tag.as_ref(), Edn::Tag(tag) if matches!(tag.ref_str(), "fn" | "macro"))
+        && matches!(view.extra.first(), Some(Edn::Map(_))) =>
+    {
+      let Some(Edn::Map(map)) = view.extra.first() else {
+        unreachable!();
+      };
+      let mut normalized = match normalize_schema_map(map) {
+        Edn::Map(map) => map,
+        _ => unreachable!(),
+      };
+      if normalized.tag_get("kind").is_none() && matches!(view.tag.as_ref(), Edn::Tag(tag) if tag.ref_str() == "macro") {
+        normalized.insert_key("kind", Edn::tag("macro"));
+      }
+      let normalized = Edn::Map(normalized);
+      validate_schema_edn_no_legacy_quotes(&normalized, owner)?;
+      return Ok(normalized);
+    }
     _ => {}
   }
   // Old format: Edn::Quote wrapping Cirru — convert to direct map Edn

package/editing-history/2026-0526-0957-match-docs-check-md.md

@@ -0,0 +1,24 @@
+# 2026-05-26 match 文档与 check-md 校验
+
+## 修改内容
+
+- 将 `match` 的文档说明统一为同时适用于 enum tuple 和 plain tuple，不再把 `tag-match` 描述成 plain tuple 的唯一入口。
+- 更新 `features/enums.md`、`features/tuples.md`、`features/common-patterns.md`、`features.md`、`quick-reference.md`、`run/agent-advanced.md` 中的推荐表述与示例。
+- 为 `agent-advanced.md` 里无法独立运行的 DOM / 事件示意片段补上 `cirru.no-check`，使 `cr docs check-md` 只校验可执行代码块。
+
+## 验证
+
+- `cargo run --bin cr -- eval $'match (:: :point 10 20)\n  (:point x y) (+ x y)\n  _ 0'`
+- `cargo run --bin cr -- docs check-md docs/features.md`
+- `cargo run --bin cr -- docs check-md docs/features/common-patterns.md`
+- `cargo run --bin cr -- docs check-md docs/features/enums.md`
+- `cargo run --bin cr -- docs check-md docs/features/error-handling.md`
+- `cargo run --bin cr -- docs check-md docs/features/traits.md`
+- `cargo run --bin cr -- docs check-md docs/features/tuples.md`
+- `cargo run --bin cr -- docs check-md docs/quick-reference.md`
+- `cargo run --bin cr -- docs check-md docs/run/agent-advanced.md`
+
+## 知识点
+
+- 原生 `match` 可以直接匹配 plain tuple；它不只适用于带 `defenum` 类型信息的 tuple。
+- 文档里的示意片段如果依赖 DOM helper、事件桥接函数或其他未加载上下文，应优先标记为 `cirru.no-check`，否则会被 `check-md` 的 `eval` 阻断。

package/editing-history/2026-0601-0003-update-callback-field-specialization.md

@@ -0,0 +1,19 @@
+# 2026-06-01 00:03 update callback field specialization
+
+## Summary
+
+- specialized `calcit.core/update` call checking so the 3rd callback arg can inherit a known record/struct field type instead of always staying at generic `fn('T) -> 'T`
+- fixed record field inference to resolve `TypeRef`-based struct annotations, not only direct `Record`/`Struct` annotations
+- aligned native `not` proc signature with calcit-core semantics by accepting dynamic input and returning `:bool`
+
+## Why
+
+- `respo` used precise type refs like `'respo.app.schema/Task`, but `infer_record_field_type` only looked through direct `Record`/`Struct` annotations, so `update task :done? not` could not see the field type
+- even after specializing `update`, Rust-side proc metadata still described `not` as `fn(:bool?) -> :bool`, which was stricter and inconsistent with the core schema/docs path
+
+## Validation
+
+- `cargo test specialize_update_uses_record_field_type_for_callback`
+- `cargo run --manifest-path /Users/chenyong/repo/calcit-lang/calcit/Cargo.toml --bin cr -- js` from `respo`
+- `yarn try-rs`
+- `cargo test`

package/editing-history/2026-0601-0005-release-0.12.36.md

@@ -0,0 +1,16 @@
+# 2026-06-01 00:05 release 0.12.36
+
+## Summary
+
+- bumped crate and npm package version from `0.12.35` to `0.12.36`
+- kept `ts-src/package.json` aligned with the root npm package metadata
+- prepared the workspace for a release lockfile refresh and tag creation
+
+## Why
+
+- this release publishes the `update` callback specialization and `not` proc typing fix after the PR checks passed
+- keeping repeated package metadata in sync avoids mismatched npm publish/version outputs during future packaging steps
+
+## Validation
+
+- `cargo update --workspace`

package/editing-history/202605210055-tree-show-cr-config-and-edit-cleanup.md

@@ -0,0 +1,81 @@
+# 202605210055 — tree show 可选路径 + cr config 顶级命令 + cr edit 清理
+
+## 修改概要
+
+### 1. `cr tree show` — `-p` 参数改为可选，缺失时警告而非报错
+
+**动机**: Agent 调用 `cr tree show ns/def` 时若忘记 `-p`，原来直接报错导致 token 浪费。
+
+**变更文件**:
+
+- `src/cli_args.rs`: `TreeShowCommand.path` 类型从 `String` → `Option<String>`，doc 注释更新
+- `src/bin/cli_handlers/tree.rs`: `handle_show` 中对 `None` 输出黄色 `[Warn]`，默认使用空路径（root）
+- `src/bin/cli_handlers/command_echo.rs`: `push_tree` Show 分支改用 `opt "path"` 宏处理 Option 类型
+
+**效果**:
+
+```
+$ cr calcit.cirru tree show "ns/def"
+[Warn] No path (-p) specified; showing from root. Use -p '0' to start from a child node.
+Type: list (4 items)
+...
+```
+
+---
+
+### 2. `cr config` — 顶级配置管理命令
+
+**动机**: `cr query config`、`cr query modules`、`cr edit config`、`cr edit add-module`、`cr edit rm-module` 分散在不同子命令下，操作配置需要记忆多个入口。新增统一入口 `cr config`。
+
+**新命令**:
+| 命令 | 等价旧命令 |
+|---|---|
+| `cr config show` | `cr query config` |
+| `cr config modules` | `cr query modules` |
+| `cr config version [value]` | `cr edit config version ...` |
+| `cr config set <key> <value>` | `cr edit config <key> <value>` |
+| `cr config add-module <path>` | `cr edit add-module <path>` |
+| `cr config rm-module <path>` | `cr edit rm-module <path>` |
+
+`cr config version` 可独立使用（无参数显示当前版本，传 `patch/minor/major` 递增，传 semver 直接设置）。
+
+**变更文件**:
+
+- `src/cli_args.rs`: 添加 `CalcitCommand::Config`、`ConfigCommand`、`ConfigSubcommand`（含 `ConfigVersionCommand`）及各子命令 struct
+- `src/bin/cli_handlers/config.rs`: 新建，实现 `handle_config_command` 及各子命令处理函数（含 `handle_version`）
+- `src/bin/cli_handlers/edit.rs`: `parse_semver_value`、`bump_semver_value` 改为 `pub(crate)`
+- `src/bin/cli_handlers/mod.rs`: 注册 `mod config` 并 re-export `handle_config_command`
+- `src/bin/cli_handlers/command_echo.rs`: 添加 `config_name`、`push_config`，并在 `should_echo_command` / `render_command_echo` 中处理 `Config` 变体
+- `src/bin/cr.rs`: 添加 `CalcitCommand::Config` 分支
+
+---
+
+### 3. `cr edit` 清理 — 移除已迁移至 `cr config` 的子命令
+
+**动机**: `cr edit add-module`、`cr edit rm-module`、`cr edit config` 与新增的 `cr config` 重复，保持单一职责。
+
+**删除内容**:
+
+- `EditSubcommand::AddModule / RmModule / Config` 及对应 struct（`cli_args.rs`）
+- `handle_add_module / handle_rm_module / handle_config` 函数体（`edit.rs`）
+- `command_echo.rs` 中 `edit_name` 和 `push_edit` 两处 match 的三个变体
+
+**保留**（被 `config.rs` 和单元测试引用）:
+
+- `pub(crate) fn parse_semver_value` — semver 字符串解析
+- `pub(crate) fn bump_semver_value` — patch/minor/major 递增
+
+**文档更新**:
+
+- `docs/run/agent-advanced.md` "模块和配置" 章节、快速参考示例 → 全部改为 `cr config` 命令
+- `docs/CalcitAgent.md` 第 9 节"cr 能力地图" → 新增"配置管理"条目
+
+---
+
+## 知识点
+
+- `argh` 中将 `#[argh(option)]` 字段类型改为 `Option<T>` 可使该选项变为可选
+- `pub(crate)` 可在同一 crate 内跨模块共享；被其他模块引用时，不能因删除调用方而一并删除
+- 新增顶级命令时需同步更新 `command_echo.rs` 的三处：`should_echo_command`、`render_command_echo`（名称映射和 token push）
+- 移除 enum 变体时，需同时检查 `command_echo.rs` 的两处 match（`edit_name` 和 `push_edit`）
+- 单元测试也会引用函数，删除前要 grep `tests` 模块确认

package/editing-history/202605312052-macro-schema-roundtrip-and-weak-types.md

@@ -0,0 +1,6 @@
+- refined weak-types reporting in `cr analyze weak-types` to classify schema/code hits with detail paths
+- tightened builtin proc signatures for list/map/set/buf-list helpers toward generic compound types
+- kept `field-match` / `record-match` macro schema inputs precise in `calcit-core` while preserving round-trip behavior
+- fixed macro schema serialization to keep non-dynamic returns like `:record` instead of dropping them during snapshot save/load
+- aligned bare marker tag parsing for `:record` and related special tags with schema normalization behavior
+- updated docs and parser tests to current wrapped schema / guidebook-loading behavior

package/editing-history/202605312059-ci-docs-test-and-fn-helper-tightening.md

@@ -0,0 +1,3 @@
+- fixed docs query test to be stable both with and without ~/.config/calcit/docs configured, matching CI runner behavior
+- tightened calcit.core fn helper schemas for &fn:apply / &fn:bind / &fn:map to reduce nested schema-dynamic usage
+- validated with focused docs test, full cargo test, runtime cr calcit/test.cirru, weak-types analyze, and yarn check-all

package/editing-history/202605312105-map-generic-weak-types-followup.md

@@ -0,0 +1,5 @@
+- tightened multiple calcit.core snapshot schemas that safely remove weak composite internals without narrowing runtime behavior: typed path lists for `assoc-in`/`get-in`/`dissoc-in`/`update-in`/`contains-in?`, typed collection helpers like `apply`, `join-str`, `foldr-shortcut`, and explicit output map generics for `map-kv` and `pairs-map`
+- corrected one weak-types false lead by changing `keys` from returning `:list` to `:set`, matching runtime/tests and moving that hit out of the list family
+- extended `cr analyze weak-types` to classify nested schema-dynamic shapes/families, include per-definition summaries, split family/shape counts by `arg`/`return` position, and show per-definition `shape@position` contributors for the remaining hotspots
+- confirmed the current lower-bound weak hits under the existing type system: `&record:to-map` for heterogeneous record values; `&tuple:params`, `&cirru-quote:to-list`, `parse-cirru-list`, `&format-ternary-tree`, `&list:flatten`, `format-cirru`, and `format-cirru-one-liner` for mixed list payloads that cannot be soundly collapsed to `list<'T>`
+- verified the final baseline at schema-dynamic=290 with `cargo test --bin cr analyze_weak_types -- --nocapture`, repeated `cargo run --bin cr -- calcit/test.cirru analyze weak-types --ns calcit.core --only schema-dynamic`, and runtime suite checks via `cargo run --bin cr -- calcit/test.cirru`

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@calcit/procs",
-    "version": "0.12.35",
+    "version": "0.12.36",
     "main": "./lib/calcit.procs.mjs",
     "devDependencies": {
         "@types/node": "^25.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calcit/procs",
-  "version": "0.12.35",
+  "version": "0.12.36",
   "main": "./lib/calcit.procs.mjs",
   "devDependencies": {
     "@types/node": "^25.7.0",