[declarative][doc] Standardize Parsable parsing method names + Update documents for release (#44)

This PR standardizes the declarative `Parsable` parsing method names
(including the dual-return APIs), updates public exports accordingly,
and refreshes docs/examples/tasks for the v0.5.0 release.

**Changes:**
- Rename `Parsable` dual-return methods for consistency (`parse_split` →
`parse_full`, `parse_with_command` → `parse_full_from_command`) and
update references.
- Remove the `Arg` alias export (and stop exporting `ArgumentLike`) to
simplify the public surface.
- Update README/user manual/planning docs/changelog and build/test tasks
(including running the new `test_wrappers.mojo`).

Author: forfudan

README.md

@@ -25,7 +25,7 @@ A feature-rich command-line argument parser library for Mojo, with both builder
 
 ## Overview
 
-ArgMojo provides two complementary styles for defining and parsing command-line arguments in Mojo: a **builder API** for maximum control (`Command` + `Argument` chains) and an optional **struct-based declarative API** inspired by Swift's [swift-argument-parser](https://github.com/apple/swift-argument-parser) (define a `Parsable` struct, call `MyArgs.parse()`, get typed results). Both styles can be mixed freely — declare 80% of your arguments in a struct, then reach for builder methods for the rest.
+ArgMojo provides two complementary styles for defining and parsing command-line arguments in Mojo: a **builder API** for maximum control (`Command` + `Argument` chains) and an optional **struct-based declarative API** inspired by Swift's [swift-argument-parser](https://github.com/apple/swift-argument-parser) (define a `Parsable` struct, call `MyArgs.parse()`, get typed results). You can mix both freely — put most of your arguments in a struct and drop down to builder methods whenever you need finer control.
 
 ArgMojo currently supports:
 
@@ -208,7 +208,16 @@ cmd.implies("force", "validated")
 var deploy = Deploy.parse_from_command(cmd^)     # Command → typed struct
 ```
 
-See `examples/declarative/` for more patterns: pure declarative, hybrid, split parse, and subcommands.
+The `Parsable` trait provides four parsing methods:
+
+|                  | `sys.argv()`     | from `Command`                  |
+| ---------------- | ---------------- | ------------------------------- |
+| returns `Self`   | `parse()`        | `parse_from_command(cmd^)`      |
+| returns `Tuple`  | `parse_full()`   | `parse_full_from_command(cmd^)` |
+
+Plus: `parse_args(args)` for testing, `to_command()` to reflect a struct into a `Command`, and `from_parse_result(result)` for subcommand write-back.
+
+See `examples/declarative/` for more patterns: pure declarative, hybrid, full parse, and subcommands.
 
 ## Usage Examples
 
@@ -225,7 +234,7 @@ ArgMojo ships with two complete example CLIs:
 | **Declarative examples**    |                                     |                                                                                                                                                                                                                                                                                                                                   |
 | `search` — pure declarative | `examples/declarative/search.mojo`  | Positional args, flags, count flags, choices, range clamping, append/collect — all via `Parsable` struct                                                                                                                                                                                                                          |
 | `deploy` — hybrid           | `examples/declarative/deploy.mojo`  | Declarative struct + builder customisation (`mutually_exclusive`, `implies`, tips, colours)                                                                                                                                                                                                                                       |
-| `convert` — split parse     | `examples/declarative/convert.mojo` | Declarative fields + extra builder args; `parse_with_command()` dual return                                                                                                                                                                                                                                                       |
+| `convert` — full parse      | `examples/declarative/convert.mojo` | Declarative fields + extra builder args; `parse_full_from_command()` dual return                                                                                                                                                                                                                                                  |
 | `jomo` — subcommands        | `examples/declarative/jomo.mojo`    | Declarative root + mix of declarative and builder subcommands; `subcommands()` hook, `from_parse_result()` dispatch                                                                                                                                                                                                               |
 
 Build both example binaries:
@@ -322,7 +331,7 @@ argmojo/
 │   └── declarative/                   # Declarative API examples
 │       ├── search.mojo                # Pure declarative (simple tool)
 │       ├── deploy.mojo                # Hybrid (declarative + builder)
-│       ├── convert.mojo               # Split parse (dual return)
+│       ├── convert.mojo               # Full parse (dual return)
 │       └── jomo.mojo                  # Subcommands (Mojo CLI lookalike)
 ├── src/
 │   └── argmojo/                       # Main package

docs/argmojo_overall_planning.md

@@ -688,7 +688,7 @@ These features use capabilities already available in Mojo 0.26.2 and can be expe
 
 - **Layered on builder** — `parser.mojo` is a consumer of `Command` + `Argument`; no new parsing engine.
 - **Swift-inspired** — Parametric wrapper types (`Option[T, ...]`, `Flag[...]`, `Positional[T, ...]`, `Count[...]`) mirror Swift's property wrappers (`@Option`, `@Flag`, `@Argument`). `Parsable` trait mirrors `ParsableCommand`.
-- **Two innovations beyond Swift**: (1) `to_command()` exposes the underlying `Command` for builder-level tweaks (groups, implications, coloured help); (2) `parse_split()` returns both typed struct + `ParseResult` for hybrid workflows.
+- **Two innovations beyond Swift**: (1) `to_command()` exposes the underlying `Command` for builder-level tweaks (groups, implications, coloured help); (2) `parse_full()` returns both typed struct + `ParseResult` for hybrid workflows.
 - **Optional** — Users who prefer the builder API are completely unaffected. Zero change to existing code.
 
 **Pre/Post run hooks** — Straightforward callback mechanism (`def(ParseResult) raises`). No special language features needed; just needs API design and a decision on execution order with subcommands.

docs/changelog.md

@@ -3,9 +3,43 @@
 This document tracks all notable changes to ArgMojo, including new features, API changes, bug fixes, and documentation updates.
 
 <!--
-Comment out unreleased changes here. This file will be edited just before each release to reflect the final changelog for that version.
+Unreleased changes should be commented out from here. This file will be edited just before each release to reflect the final changelog for that version. Otherwise, the users would be confused.
 -->
 
+## 20260404 (v0.5.0)
+
+ArgMojo v0.5.0 introduces the **struct-based declarative API** — define a `Parsable` struct with typed wrapper fields (`Option`, `Flag`, `Positional`, `Count`), call `MyArgs.parse()`, and get typed results. The declarative API coexists with the existing builder API and bridges between them via `to_command()` / `parse_from_command()`. This release also adds asterisk-masked password input and reorganises internal modules.
+
+ArgMojo v0.5.0 targets Mojo v0.26.2.
+
+### ⭐️ New in v0.5.0
+
+1. **Declarative API core** — `Parsable` trait with compile-time reflection over wrapper-typed fields. Conforming structs need only declare fields and provide `description()`; all parsing, Command-building, and write-back methods are provided as trait defaults (PR #34, #35, #37, #40).
+2. **Wrapper types** — `Option[T, ...]`, `Flag[...]`, `Positional[T, ...]`, `Count[...]` parametric structs encode CLI metadata as compile-time parameters. Conform to the internal `ArgumentLike` trait with `add_to_command()` / `read_from_result()` hooks (PR #34).
+3. **Auto-initialisation** — `Parsable.__init__` uses `mark_initialized` + `comptime for` + `UnsafePointer.init_pointee_move` to default-construct all fields via reflection. Users never need to write `__init__` (PR #37).
+4. **Hybrid bridge** — `to_command()` reflects a `Parsable` struct into an owned `Command` for builder-level customisation; `parse_from_command(cmd^)` parses back into a typed struct (PR #35, #40).
+5. **Dual-return parsing** — `parse_full()` returns `Tuple[Self, ParseResult]` for workflows that need both typed struct fields and raw `ParseResult` access (e.g. subcommand dispatch). `parse_full_from_command(cmd^)` does the same from a pre-configured Command (PR #40, #42).
+6. **Subcommand support** — `subcommands()` hook on `Parsable` returns `List[Command]`; called automatically by `to_command()` for recursive tree assembly. `run(self)` method for leaf command execution. `from_parse_result()` for typed write-back from subcommand results (PR #39, #43).
+7. **Asterisk-masked password input** — `.password[True]()` on `Argument` echoes `*` for each keystroke (sudo-rs style), complementing the existing `.password()` which hides input entirely. Uses raw terminal mode with ICANON/ISIG disabled (PR #32).
+
+### 🦋 Changed in v0.5.0
+
+1. Remove `Arg` alias for `Argument` and drop `ArgumentLike` from the public export list. The public API now exports: `Argument`, `Command`, `ParseResult`, `Parsable`, `Option`, `Flag`, `Positional`, `Count` (PR #42).
+2. `subcommands()` hook signature changed from `subcommands(mut cmd: Command) raises` to `subcommands() raises -> List[Command]` — returns a list of Commands instead of mutating one (PR #43).
+3. Reorganise `Argument` and `Command` source files into clearly grouped internal sections for readability (PR #33).
+
+### 📚 Documentation and testing in v0.5.0
+
+- Add `docs/declarative_api_planning.md` — comprehensive design document for the declarative API (PR #33).
+- Add 4 declarative examples: `search.mojo` (pure declarative), `deploy.mojo` (hybrid), `convert.mojo` (full parse + extra builder args), `jomo.mojo` (subcommands with hybrid tree) (PR #41).
+- Add 4 test modules: `test_wrappers.mojo` (wrapper defaults, copy/move, `Flag.__bool__`), `test_declarative.mojo` (to_command, parse_args, from_parse_result), `test_hybrid.mojo` (builder customisation, mutually exclusive, implies, configure pattern), `test_subcommands_declarative.mojo` (flat/nested subcommands, run() dispatch, dual return) (PR #38, #39).
+- Add `test_interactive.mojo` for interactive prompting edge cases (PR #33).
+- Add method matrix table to README, user manual, and planning doc.
+- Update README with declarative API Quick Start, examples table, and project structure.
+- Update user manual with declarative API usage guide, full-parse section, and API summary.
+
+---
+
 ## 20260321 (v0.4.0)
 
 ArgMojo v0.4.0 adds interactive prompting, password input, confirmation, argument parents, custom usage lines, response files, CJK-aware help formatting, and full-width auto-correction. The builder API is fully parameterised with compile-time `StringLiteral` parameters. The codebase is migrated to Mojo v0.26.2 and the test suite consolidated from 20 files into 8 modules.