docs(stock): document dividend commands

docs/journals/260720-1612-stock-dividend-command-naming.md

@@ -0,0 +1,34 @@
+# Stock Dividend Command Naming Journal
+
+## Context
+
+Researched official VSDC dividend notices and brainstormed clearer stock command
+contracts for cash, share, and mixed dividend events.
+
+## What Happened
+
+- Approved `/stock_cash_dividend <vnd_per_share> <TICKER>` for cash dividends.
+- Approved `/stock_share_dividend <owned:new> <TICKER>` for share dividends.
+- Approved `/stock_dividend <vnd_per_share> <owned:new> <TICKER>` for mixed
+  cash-and-share dividends.
+- Official examples support ratios such as `4:1` and `100:10`.
+- No implementation changes made yet.
+
+## Decisions
+
+- Share ratios use `owned:new`; both parts must be positive whole numbers.
+- New shares use integer floor division. Fractional entitlements discarded.
+- Cash input means VND paid per pre-event share.
+- Mixed dividends calculate cash and new shares from the same pre-event holding,
+  then persist both results atomically.
+- Stats history needs a one-time, idempotent migration: existing
+  `/stock_dividend` usage becomes `/stock_cash_dividend`, and `/stock_bonus`
+  usage becomes `/stock_share_dividend`. The new mixed `/stock_dividend` starts
+  with fresh stats.
+
+## Next Steps
+
+- Create an implementation plan covering handlers, registration, user-facing
+  text, command menu, atomic storage behavior, stats migrations, and tests.
+- Implement the approved zero-result behavior: reject share-only payouts, but
+  still credit cash and report zero new shares for mixed payouts.

docs/journals/260720-1621-stock-dividend-command-plan.md

@@ -0,0 +1,33 @@
+# Stock Dividend Command Plan Journal
+
+## Context
+
+Created the implementation plan at
+`plans/260720-1616-stock-dividend-commands/` from the approved research and
+brainstorm decisions.
+
+## What Happened
+
+- Added three pending phases: implement ratio dividend commands, migrate command
+  statistics, and verify user-facing contracts.
+- Planned `/stock_cash_dividend` with VND/share, `/stock_share_dividend` with an
+  `owned:new` ratio, and combined `/stock_dividend` using both inputs.
+- Preserved floor rounding, pre-event holdings, and one atomic portfolio save.
+- Defined zero-share behavior: reject share-only events; combined events still
+  credit cash.
+- Tightened migration design after review: each stats row gets a `prepared`
+  checkpoint containing its exact final target count. Crash retries set that
+  count instead of incrementing again.
+- Could not persist the active-plan selection because `CK_SESSION_ID` was unset.
+
+## Status
+
+- Plan: pending
+- Progress: 0/3 phases complete
+- Source implementation: not started
+
+## Next Steps
+
+- Execute the three planned phases, beginning with command contracts and tests.
+- Keep the stats migration before module registration so the reused
+  `/stock_dividend` name cannot misattribute historical usage.

docs/journals/260720-1636-stock-dividend-plan-validation.md

@@ -0,0 +1,31 @@
+# Stock Dividend Plan Validation Journal
+
+## Context
+
+Validated `plans/260720-1616-stock-dividend-commands/plan.md` and its three
+pending phase documents before implementation.
+
+## Validation Result
+
+- Standard verification: 30 checked, 30 verified, 0 failed, 0 unverified.
+- Confirmed cash input is a positive whole VND amount per share.
+- Confirmed any positive whole-number `owned:new` ratio is accepted and echoed
+  unreduced.
+- Confirmed repeated manual calls are allowed. No event ledger or duplicate-call
+  restriction; caller owns correctness.
+- Confirmed permanent global and per-row migration markers. Incomplete runs
+  resume from `prepared` checkpoints using their exact target counts.
+- Propagated these decisions through all three phase documents.
+- Whole-plan consistency sweep reconciled one stale float-acceptance reference
+  with integer-input wording and found zero contradictions.
+
+## Status
+
+- Plan validation: complete
+- Plan implementation: not started
+- Source changes: none
+
+## Next Steps
+
+- Execute the validated phases in order: command behavior, stats migration, then
+  user-contract and full-project verification.

docs/journals/260720-1715-stock-dividend-commands.md

@@ -0,0 +1,67 @@
+# Stock Dividend Commands Journal
+
+## Context
+
+Implemented the validated stock-dividend plan: clearer manual commands,
+ratio-based share entitlement, and historical stats preservation.
+
+## What Changed
+
+- Added `/stock_cash_dividend <vnd_per_share> <TICKER>` for positive whole-VND
+  cash credits.
+- Added `/stock_share_dividend <owned:new> <TICKER>` with unreduced ratio
+  preservation and floor-rounded whole shares.
+- Changed `/stock_dividend <vnd_per_share> <owned:new> <TICKER>` to apply cash
+  and shares from the same pre-event holding with one portfolio save.
+- Share-only zero entitlement rejects with the minimum holding; combined events
+  still credit cash when shares round to zero.
+- Updated registration, command menu, usage text, README, and contract tests;
+  removed `/stock_bonus` from active commands.
+
+## Stats Migration
+
+- Migrates `stock_dividend -> stock_cash_dividend` and
+  `stock_bonus -> stock_share_dividend`, including anonymous and per-user rows.
+- Merges existing target counts without loss.
+- Permanent global and per-row markers retain migration history.
+- Each row stores a `prepared` exact target count before mutation. Retries set
+  that count after any write-boundary failure, preventing double increments.
+
+## Review Findings
+
+- Guarded `strconv.ParseInt` range errors so its saturated return value cannot be
+  accepted as valid input.
+- Added exact `int64` share formatting so quantities above `2^53` do not lose
+  digits through `float64` conversion.
+- Enforced exact float-backed VND balance addition at the `2^53` boundary;
+  inexact sums reject without saving.
+- Reviewer: 9/10, approve. Adversarial review: PASS; no disproven claims or
+  reachable regressions.
+
+## Decisions
+
+- Ratios remain positive integer `owned:new` values and are echoed as entered;
+  no normalization.
+- Commands are manual adjustments. Repeated calls remain allowed, with no event
+  ledger or duplicate-call guard; caller owns correctness.
+- Overflow, exactness, ticker, and syntax validation remain mandatory despite
+  the manual workflow.
+
+## Verification
+
+- Passed: `go test ./internal/modules/stock`
+- Passed: `go test ./internal/modules/stats`
+- Passed: `go test ./cmd/server`
+- Passed: `go test ./...`
+- Passed: `go vet ./...`
+- Passed: `telegram-commands.json` PowerShell `ConvertFrom-Json`
+- Passed: `git diff --check` (line-ending warnings only)
+- Skipped: Mongo-backed tests because `MONGODB_TEST_URL` was unset.
+- Skipped: `golangci-lint run` because the binary was not installed.
+
+## Next Considerations
+
+- Run Mongo-backed migration tests when a test database is available.
+- Run the lint gate when `golangci-lint` is installed.
+- After deployment, verify migrated counts and retained system markers before
+  considering migration-runtime cleanup; keep historical stats and markers.