[doc] Update documents for release (#31)

This PR prepares the repository for the v0.4.0 release by updating
documentation/release notes, aligning stringification with Mojo’s
`Writable` conventions, and refreshing the pixi workspace
configuration/lockfiles.

**Changes:**
- Remove `__str__` implementations from core structs and rely on
`write_to` (`Writable`) for string representations.
- Update docs (user manual, changelog, README, planning doc) for Mojo
v0.26.2+/v0.4.0 release content.
- Bump pixi workspace version and refresh pixi tasks/lockfile to reflect
the new environment.

Author: forfudan

README.md

@@ -7,7 +7,7 @@ A command-line argument parser library for [Mojo](https://www.modular.com/mojo),
  -->
 
 [![Version](https://img.shields.io/github/v/tag/forfudan/argmojo?label=version&color=blue)](https://github.com/forfudan/argmojo/releases)
-[![Mojo](https://img.shields.io/badge/mojo-0.26.1-orange)](https://docs.modular.com/mojo/manual/)
+[![Mojo](https://img.shields.io/badge/mojo-0.26.2-orange)](https://docs.modular.com/mojo/manual/)
 [![pixi](https://img.shields.io/badge/pixi%20add-argmojo-brightgreen)](https://prefix.dev/channels/modular-community/packages/argmojo)
 [![User manual](https://img.shields.io/badge/user-manual-purple)](https://github.com/forfudan/argmojo/wiki)
 
@@ -51,8 +51,34 @@ ArgMojo provides a builder-pattern API for defining and parsing command-line arg
 - **Append / collect action**: `--tag x --tag y` collects repeated options into a list with `.append()`
 - **One-required groups**: require at least one argument from a group (e.g., must provide `--json` or `--yaml`)
 - **Value delimiter**: `--env dev,staging,prod` splits by delimiter into a list with `.delimiter[","]()`
-- **Multi-value options (nargs)**: `--point 10 20` consumes N consecutive values with `.nargs(N)`
+- **Multi-value options (nargs)**: `--point 10 20` consumes N consecutive values with `.number_of_values[N]()`
+- **Key-value map options**: `--define CC=gcc --define CXX=g++` collects key=value pairs with `.map_option()`
+- **Numeric range validation**: `--level 5` checked against `[min, max]` bounds with `.range[1, 10]()`; optional clamping with `.clamp()`
+- **Conditional requirements**: `--output` required when `--save` is present
+- **Aliases**: alternative long names (e.g., `--colour` and `--color`) with `.alias_name["color"]()`
+- **Deprecated arguments**: emit a warning but continue parsing
+- **Custom tips**: add tip lines below the help message
+- **Mutual implication**: `--debug` automatically sets `--verbose` with `.implies()`
+- **Subcommands**: hierarchical commands (`app search`, `app init`), nested subcommands (`app remote add`), persistent (global) flags, subcommand aliases, hidden subcommands
 - **Shell completion script generation**: `generate_completion("bash"|"zsh"|"fish")` produces a complete tab-completion script for your CLI
+- **Typo suggestions**: Levenshtein-distance "did you mean …?" for misspelled options and subcommands
+- **Interactive prompting**: `.prompt()` to interactively ask for missing values
+- **Password / masked input**: `.password()` to hide typed input during prompts
+- **Confirmation option**: `confirmation_option()` to add a `--yes`/`-y` skip-confirmation flag
+- **Argument parents**: `add_parent()` to share argument definitions across commands
+- **Custom usage line**: `usage()` to override the auto-generated usage string
+- **Response files**: `@args.txt` expansion (temporarily disabled due to a Mojo compiler bug)
+- **CJK-aware help alignment**: CJK characters treated as 2-column-wide
+- **CJK full-width auto-correction**: fullwidth `－－ｖｅｒｂｏｓｅ` → `--verbose` with a warning
+- **CJK punctuation detection**: em-dash `——verbose` → `--verbose`
+- **Argument groups**: `.group["Network"]()` to group arguments under dedicated help sections
+- **Default-if-no-value**: `--compress` uses a fallback; `--compress=bzip2` overrides
+- **Require equals syntax**: `--key=value` required, `--key value` rejected
+- **Remainder positional**: `.remainder()` consumes all remaining tokens
+- **Allow hyphen values**: `.allow_hyphen_values()` accepts `-` as a regular value (stdin convention)
+- **Partial parsing**: `parse_known_arguments()` collects unrecognised options instead of erroring
+- **Compile-time validation**: builder parameters validated at `mojo build` time via `comptime assert`
+- **Registration-time validation**: group constraint typos caught when the program starts, not when the user runs it
 
 ---
 
@@ -62,6 +88,8 @@ My goal is to provide a Mojo-idiomatic argument parsing library that can be easi
 
 ## Installation
 
+### Package Manager
+
 ArgMojo is available in the modular-community `https://repo.prefix.dev/modular-community` package repository. To access this repository, add it to your `channels` list in your `pixi.toml` file:
 
 ```toml
@@ -75,17 +103,14 @@ Then, you can install ArgMojo using any of these methods:
 1. In the `mojoproject.toml` file of your project, add the following dependency:
 
     ```toml
-    argmojo = "==0.3.0"
+    argmojo = "*"
     ```
 
     Then run `pixi install` to download and install the package.
 
-The following table summarizes the package versions and their corresponding Mojo versions:
+### Using mojopkg
 
-| `argmojo` version | `mojo` version | package manager |
-| ----------------- | -------------- | --------------- |
-| 0.1.0             | ==0.26.1       | pixi            |
-| 0.3.0             | ==0.26.1       | pixi            |
+The package manager may not be up to date with the latest ArgMojo release. If you want to use the latest version, you can download the `mojopkg` file from the [latest release](https://github.com/forfudan/argmojo/releases) and include it in your project directory.
 
 ## Quick Start
 
@@ -95,7 +120,7 @@ Here is a simple example of how to use ArgMojo in a Mojo program. See `examples/
 from argmojo import Argument, Command
 
 
-fn main() raises:
+def main() raises:
     var app = Command("mgrep", "Search for PATTERN in each FILE.", version="1.0.0")
 
     # Positional arguments
@@ -144,10 +169,12 @@ For detailed explanations and more examples of every feature, see the **[User Ma
 
 ArgMojo ships with two complete example CLIs:
 
-| Example                  | File                  | Features                                                                                                                                                                                                                                                                                                                          |
-| ------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mgrep` — simulated grep | `examples/mgrep.mojo` | Positional args, flags, count flags, negatable flags, choices, value_name, append/collect, value delimiter, nargs, mutually exclusive groups, required-together groups, conditional requirements, numeric range, key-value map, aliases, deprecated args, hidden args, negative-number passthrough, `--` stop marker, custom tips |
-| `mgit` — simulated git   | `examples/mgit.mojo`  | Subcommands (clone/init/add/commit/push/pull/log/remote/branch/diff/tag/stash), nested subcommands (remote add/remove/rename/show), persistent (global) flags, per-command args, mutually exclusive groups, choices, aliases, deprecated args, custom tips, shell completion script generation                                    |
+| Example                   | File                  | Features                                                                                                                                                                                                                                                                                                                          |
+| ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mgrep` — simulated grep  | `examples/mgrep.mojo` | Positional args, flags, count flags, negatable flags, choices, value_name, append/collect, value delimiter, nargs, mutually exclusive groups, required-together groups, conditional requirements, numeric range, key-value map, aliases, deprecated args, hidden args, negative-number passthrough, `--` stop marker, custom tips |
+| `mgit` — simulated git    | `examples/mgit.mojo`  | Subcommands (clone/init/add/commit/push/pull/log/remote/branch/diff/tag/stash), nested subcommands (remote add/remove/rename/show), persistent (global) flags, per-command args, mutually exclusive groups, choices, aliases, deprecated args, custom tips, shell completion script generation                                    |
+| `demo` — feature showcase | `examples/demo.mojo`  | Comprehensive showcase of all ArgMojo features in a single CLI                                                                                                                                                                                                                                                                    |
+| `yu` — Chinese CLI        | `examples/yu.mojo`    | CJK-aware help formatting, full-width auto-correction, CJK punctuation detection                                                                                                                                                                                                                                                  |
 
 Build both example binaries:
 
@@ -232,10 +259,14 @@ pixi run clean
 ```txt
 argmojo/
 ├── docs/                              # Documentation
+│   ├── argmojo_overall_planning.md    # Planning document and feature matrix
+│   ├── changelog.md                   # Release changelog
 │   └── user_manual.md                 # User manual with detailed examples
 ├── examples/
+│   ├── demo.mojo                      # Comprehensive feature showcase
 │   ├── mgrep.mojo                     # grep-like CLI (no subcommands)
-│   └── mgit.mojo                      # git-like CLI (with subcommands)
+│   ├── mgit.mojo                      # git-like CLI (with subcommands)
+│   └── yu.mojo                        # Chinese-language CLI (CJK features)
 ├── src/
 │   └── argmojo/                       # Main package
 │       ├── __init__.mojo              # Package exports

docs/argmojo_overall_planning.md

@@ -10,7 +10,7 @@ At the moment, Mojo does not have a mature command-line argument parsing library
 
 ## 2. Cross-Language Research Summary
 
-This section summarises the key design patterns and features from well-known arg parsers across multiple languages. The goal is to extract **universally useful ideas** that are feasible in Mojo 0.26.1, and to exclude features that depend on language-specific capabilities (macros, decorators, reflection, closures-as-first-class) that Mojo does not yet provide.
+This section summarises the key design patterns and features from well-known arg parsers across multiple languages. The goal is to extract **universally useful ideas** that are feasible in Mojo 0.26.2, and to exclude features that depend on language-specific capabilities (macros, decorators, reflection, closures-as-first-class) that Mojo does not yet provide.
 
 ### 2.1 Libraries Surveyed
 
@@ -55,7 +55,7 @@ These features appear across multiple libraries and depend only on string operat
 | Key-value map (`-Dkey=val`)        | —        | —     | —     | —    | Java `-D`, Docker `-e`       | **Done**      |
 | Aliases for long names             | —        | —     | ✓     | ✓    |                              | **Done**      |
 | Deprecated arguments               | ✓ (3.13) | —     | ✓     | —    |                              | **Done**      |
-| Negative number passthrough        | ✓        | —     | —     | ✓    | Essential for `decimo`       | **Done**      |
+| Negative number / stdin `−`        | ✓        | —     | ✓     | ✓    | `allow_hyphen_values()`      | **Done**      |
 | Subcommands                        | ✓        | ✓     | ✓     | ✓    |                              | **Done**      |
 | Auto-added `help` subcommand       | —        | —     | ✓     | ✓    | git, cargo, kubectl          | **Done**      |
 | Persistent (global) flags          | —        | —     | ✓     | ✓    | git `--no-pager` etc.        | **Done**      |
@@ -70,13 +70,11 @@ These features appear across multiple libraries and depend only on string operat
 | Interactive prompting              | —        | ✓     | —     | —    |                              | **Done**      |
 | Password / masked input            | —        | ✓     | —     | —    |                              | **Done**      |
 | Confirmation (`--yes` / `-y`)      | —        | ✓     | —     | —    |                              | **Done**      |
-| Pre/Post run hooks                 | —        | —     | ✓     | —    |                              | Phase 5       |
 | REMAINDER number_of_values         | ✓        | —     | —     | —    |                              | **Done**      |
 | Partial parsing (known args)       | ✓        | —     | —     | ✓    |                              | **Done**      |
 | Require equals syntax              | —        | —     | —     | ✓    |                              | **Done**      |
 | Default-if-no-value                | ✓        | —     | —     | ✓    |                              | **Done**      |
 | Mutual implication (`implies`)     | —        | —     | —     | —    | ArgMojo unique feature       | **Done**      |
-| Stdin value (`-` convention)       | —        | —     | ✓     | —    | Unix convention              | Phase 5       |
 | Shell completion script generation | —        | ✓     | ✓     | ✓    | bash / zsh / fish            | **Done**      |
 | Argument groups in help            | ✓        | —     | ✓     | ✓    |                              | **Done**      |
 | Value-name wrapping control        | —        | —     | —     | ✓    | clap, cargo, pixi, git       | **Done**      |
@@ -86,6 +84,7 @@ These features appear across multiple libraries and depend only on string operat
 | Typed retrieval (`get_int()` etc.) | ✓        | ✓     | ✓     | ✓    |                              | **Done**      |
 | Comptime `StringLiteral` params    | —        | —     | —     | ✓    | clap derive macros           | **Done**      |
 | Registration-time name validation  | —        | —     | —     | ✓    | clap panic on unknown ID     | **Done**      |
+| Pre/Post run hooks                 | —        | —     | ✓     | —    |                              | Phase unknown |
 | `Parseable` trait for type params  | —        | —     | —     | ✓    |                              | Phase unknown |
 | Derive / struct-based schema       | —        | —     | —     | ✓    | Requires Mojo macros         | Phase unknown |
 | Enum → type mapping (real enums)   | —        | —     | —     | ✓    | Requires reflection          | Phase unknown |
@@ -110,9 +109,9 @@ These features appear across multiple libraries and depend only on string operat
 Mojo provides `sys.argv()` to access command-line arguments:
 
 ```mojo
-from sys import argv
+from std.sys import argv
 
-fn main():
+def main():
     var args = argv()
     for i in range(len(args)):
         print("arg[", i, "] =", args[i])
@@ -151,27 +150,14 @@ src/argmojo/
 ├── parse_result.mojo               # ParseResult struct — parsed values
 └── utils.mojo                      # Internal utilities — ANSI colours, display helpers
 tests/
-├── test_parse.mojo                 # Core parsing tests (flags, values, shorts, etc.)
-├── test_groups.mojo                # Group constraint tests (exclusive, conditional, etc.)
-├── test_collect.mojo               # Collection feature tests (append, delimiter, number_of_values)
-├── test_help.mojo                  # Help output tests (formatting, colours, alignment)
-├── test_extras.mojo                # Range, map, alias, deprecated tests
-├── test_subcommands.mojo           # Subcommand tests (dispatch, help sub, unknown sub, etc.)
-├── test_negative_numbers.mojo      # Negative number passthrough tests
-├── test_persistent.mojo            # Persistent (global) flag tests
-├── test_typo_suggestions.mojo      # Levenshtein typo suggestion tests
-├── test_completion.mojo            # Shell completion script generation tests
-├── test_implies.mojo               # Mutual implication and cycle detection tests
-├── test_const_require_equals.mojo  # default_if_no_value and require_equals tests
-├── test_response_file.mojo         # response file (@args.txt) expansion tests
-├── test_remainder_known.mojo       # remainder, parse_known_arguments, allow_hyphen_values tests
-├── test_fullwidth.mojo             # full-width → half-width auto-correction tests
-├── test_groups_help.mojo           # argument groups in help + value_name wrapping tests
-├── test_prompt.mojo                # interactive prompting tests
-├── test_parents.mojo               # argument parents (shared definitions) tests
-├── test_confirmation.mojo          # confirmation option (--yes / -y) tests
-├── test_password.mojo              # password / masked input tests
-└── test_usage.mojo                 # usage line customisation tests
+├── test_parse.mojo                 # Core parsing + negative number passthrough tests
+├── test_options.mojo               # default_if_no_value, require_equals, range, clamp, map, aliases, deprecated, remainder, parse_known, collection tests
+├── test_groups.mojo                # Mutually exclusive, required-together, one-required, conditional, implies, argument groups in help, value_name wrapping tests
+├── test_help.mojo                  # Help formatting, ANSI colours, CJK alignment, NO_COLOR, custom usage, fullwidth correction tests
+├── test_subcommands.mojo           # Subcommand dispatch, persistent/global flags, argument parents tests
+├── test_completion.mojo            # Shell completion (bash/zsh/fish) + Levenshtein typo suggestion tests
+├── test_interactive.mojo           # Interactive prompting, password/masked input, confirmation tests
+└── test_response_file.mojo         # Response file (@args.txt) expansion tests (⚠ disabled due to compiler bug)
 examples/
 ├── demo.mojo                       # comprehensive showcase of all ArgMojo features
 ├── mgrep.mojo                      # grep-like CLI example (no subcommands)
@@ -253,7 +239,7 @@ examples/
 ```mojo
 from argmojo import Command, Argument
 
-fn main() raises:
+def main() raises:
     var command = Command("demo", "A CJK-aware text search tool which supports pinyin and Yuhao IME")
 
     # Positional arguments