Implement Stage 19 language generation

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -50,7 +50,7 @@ body:
     id: version
     attributes:
       label: Manas version / commit
-      placeholder: e.g. main, v0.1.0, or commit SHA
+      placeholder: e.g. main, v2.0.0, or commit SHA
 
   - type: textarea
     id: environment

.github/release-notes/v2.0.0.md

@@ -0,0 +1,78 @@
+# Manas v2.0.0 — Manas v2 Release
+
+> A local brain that starts empty, learns facts into neural weights, grows when
+> needed, protects old knowledge, refreshes stale memories explicitly, and can
+> generate fluent sentences from what it learned.
+
+Manas v2.0.0 is the first full Manas v2 release. It replaces the v1 sidecar and
+text-search design with one `.manas` brain file whose neural weights are the
+source of answers.
+
+## What This Release Proves
+
+```bash
+./manas teach "A cat is a small domesticated animal with fur and whiskers."
+./manas teach "The Eiffel Tower is located in Paris France and was built in 1889."
+./manas teach "Albert Einstein developed the theory of relativity."
+
+rm -f brain.manas.sources brain.manas.sourceindex
+rm -f brain.manas.seq brain.manas.transformer brain.manas.langmeta
+
+./manas ask "What is a cat?"
+# Answered from: neural weights
+
+./manas generate "What is a cat?"
+# Generated from: neural weights
+```
+
+## Highlights
+
+- Associative memory engine: taught facts are retrieved from neural weights.
+- Anti-forgetting: frozen neurons and frozen output edges cannot be overwritten.
+- Growth: the brain starts empty and grows neurons or hidden layers when needed.
+- Persistence: everything lives in one CRC32-checked `.manas` file.
+- Ingestion: teach raw text, local files, and folders with supported formats.
+- Diagnostics: inspect the brain, list neurons, and trace query activations.
+- Compression: safely forget low-importance mergeable hidden neurons.
+- Freshness: stale learned facts are detected and surfaced during answers.
+- Refresh: `manas refresh` explicitly updates stale internet-sensitive memories.
+- Generation: `manas generate` and `manas ask --fluent` produce local fluent text
+  from neural-weight answer concepts.
+- Benchmarks: B1-B9 cover teach, ask, generate, save, load, tokenization,
+  anti-forgetting, memory footprint, and brain file growth.
+
+## Install
+
+```bash
+curl -fsSL https://github.com/AarambhDevHub/manas/releases/download/v2.0.0/manas-linux-x86_64.tar.gz \
+  | tar -xz
+sudo mv manas-linux-x86_64 /usr/local/bin/manas
+manas --help
+```
+
+## Build from Source
+
+```bash
+git clone https://github.com/AarambhDevHub/manas.git
+cd manas
+cargo build --workspace --release
+./target/release/manas --help
+```
+
+## Verification Gates
+
+The v2 release workflow runs:
+
+- `cargo fmt --all -- --check`
+- `cargo test --workspace`
+- `cargo clippy --workspace --all-targets -- -D warnings`
+- `cargo build --workspace --release`
+- `cargo bench -p manas-benches -- --quick`
+- `bash demo.sh`
+
+## Honest Claim
+
+Manas v2.0.0 is not a ChatGPT replacement and not a general-purpose LLM. It is a
+local continual-learning research project that stores taught knowledge in neural
+weights, retrieves it from weights alone, and formats those learned concepts into
+answers without sidecar text search.

.github/workflows/release.yml

@@ -8,9 +8,13 @@ on:
 permissions:
   contents: write
 
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
 jobs:
   release-linux:
-    name: Build Linux Release
+    name: Build Linux x86_64 Release
     runs-on: ubuntu-latest
 
     steps:
@@ -29,15 +33,25 @@ jobs:
       - name: Run tests
         run: cargo test --workspace
 
+      - name: Run clippy
+        run: cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Run benchmark smoke
+        run: cargo bench -p manas-benches -- --quick
+
       - name: Build release binary
         run: cargo build --workspace --release
 
+      - name: Run neural-weights demo
+        run: bash demo.sh
+
       - name: Prepare artifact
         run: |
           mkdir -p dist
           cp target/release/manas dist/manas-linux-x86_64
           chmod +x dist/manas-linux-x86_64
           tar -czf dist/manas-linux-x86_64.tar.gz -C dist manas-linux-x86_64
+          (cd dist && sha256sum manas-linux-x86_64.tar.gz > SHA256SUMS)
 
       - name: Resolve release notes path
         id: notes
@@ -55,15 +69,21 @@ jobs:
         if: steps.notes.outputs.found == 'true'
         uses: softprops/action-gh-release@v2
         with:
+          name: Manas ${{ github.ref_name }}
           body_path: ${{ steps.notes.outputs.path }}
           files: |
             dist/manas-linux-x86_64.tar.gz
+            dist/SHA256SUMS
           generate_release_notes: false
+          fail_on_unmatched_files: true
 
       - name: Create GitHub Release (auto notes)
         if: steps.notes.outputs.found == 'false'
         uses: softprops/action-gh-release@v2
         with:
+          name: Manas ${{ github.ref_name }}
           files: |
             dist/manas-linux-x86_64.tar.gz
+            dist/SHA256SUMS
           generate_release_notes: true
+          fail_on_unmatched_files: true

ARCHITECTURE.md

@@ -29,7 +29,8 @@
     - [manas-learn](#103-manas-learn)
     - [manas-ingest](#104-manas-ingest)
     - [manas-agent](#105-manas-agent)
-    - [manas-cli](#106-manas-cli)
+    - [manas-language](#106-manas-language)
+    - [manas-cli](#107-manas-cli)
 11. [The .manas Binary Format](#11-the-manas-binary-format)
 12. [Data Flow — Full Pipeline](#12-data-flow--full-pipeline)
 13. [Neuron Lifecycle](#13-neuron-lifecycle)
@@ -460,25 +461,31 @@ manas/
 │   └── src/
 │       └── lib.rs          ← DuckDuckGo client, fixtures, refresh planner
 │
+├── manas-language/         ← FLUENT GENERATION
+│   ├── Cargo.toml          ← deps: manas-core, manas-learn
+│   └── src/
+│       └── lib.rs          ← sentence generation over neural concepts
+│
 ├── manas-cli/              ← USER INTERFACE
-    ├── Cargo.toml          ← deps: all crates above
-    └── src/
-        └── main.rs         ← std-only arg parsing, command routing, formatting
+│   ├── Cargo.toml          ← deps: all runtime crates
+│   └── src/
+│       └── main.rs         ← std-only arg parsing, command routing, formatting
 │
 └── manas-benches/          ← TOOLING ONLY
     └── benches/
-        └── bench.rs        ← B1-B8 benchmark harness, BENCHMARKS.md generator
+        └── bench.rs        ← B1-B9 benchmark harness, BENCHMARKS.md generator
 ```
 
-**Runtime crates: 6** (v1 had 9 — simpler is better)
+**Runtime crates: 7**
 
 **Tooling crates: 1** (`manas-benches`, not part of the runtime path)
 
-**No `manas-language` crate** — the transformer path from v1 is removed.
-Language generation is a future milestone, not the foundation.
+**`manas-language` is generation-only** — it turns neural-weight query concepts
+into fluent sentences. It does not store knowledge, answer from sidecars, or
+replace associative memory.
 
 **`manas-agent` is refresh-only** — it powers explicit `manas refresh`.
-It is not used by `manas ask`, which remains neural-weight retrieval only.
+It is not used by default `manas ask`, which remains neural-weight retrieval only.
 
 **No `manas-memory` crate** — importance scoring and protection now live
 directly inside `manas-core` and `manas-learn` where they belong.
@@ -900,7 +907,33 @@ through `manas-learn`. It does not answer questions directly.
 
 ---
 
-### 10.6 `manas-cli`
+### 10.6 `manas-language`
+
+Fluent language generation over associative-memory answers. This crate keeps
+generation separate from retrieval: `manas-learn` answers from weights first,
+then `manas-language` realizes the decoded concepts into a sentence.
+
+**Dependencies:** `manas-core`, `manas-learn`
+
+```rust
+pub struct GenerationConfig {
+    pub max_words: usize,
+}
+
+pub struct GenerationResult {
+    pub text: String,
+    pub confidence: f32,
+    pub answered_from: AnswerSource,
+    pub freshness_warning: Option<FreshnessWarning>,
+    pub concepts: Vec<String>,
+}
+
+pub struct LanguageGenerator { ... }
+```
+
+No `.manas` format change is required. Generation is deterministic and local.
+
+### 10.7 `manas-cli`
 
 User-facing commands. Thin layer over the learning engine.
 **All business logic lives in the crates above. The CLI only routes and formats.**
@@ -913,7 +946,11 @@ external CLI parsing can be added later if needed.
 ```
 manas teach <text|file|folder> [--recursive]
                           Teach raw text, a supported file, or a folder
-manas ask "<QUESTION>"    Ask a question — answered from neural weights
+manas ask [--fluent] "<QUESTION>"
+                          Ask a question from neural weights; `--fluent`
+                          formats the neural concepts as a sentence
+manas generate "<PROMPT>" [--max-words N]
+                          Generate a fluent sentence from learned neural concepts
 manas inspect             Show brain, network, learning, freshness, source, layer stats
 manas neurons             List/filter neurons with importance, protection, source
 manas trace "<QUESTION>"  Trace query variants, activations, and output values
@@ -969,6 +1006,19 @@ Answered from
   neural weights
 ```
 
+#### `manas generate` Output Format
+
+```
+Generated
+  A cat is a small domesticated animal with fur and whiskers.
+
+Confidence
+  0.87
+
+Generated from
+  neural weights
+```
+
 ---
 
 ## 11. The .manas Binary Format
@@ -1186,7 +1236,8 @@ Note
   This knowledge may be outdated (Fast freshness, learned 47 days ago).
 ```
 
-The internet agent (future milestone) will use freshness to decide when to re-fetch.
+The internet agent uses freshness to decide when explicit refresh should
+re-fetch stale memories.
 
 ---
 
@@ -1233,6 +1284,7 @@ benchmark harness:
 | B6 | Full anti-forgetting proof |
 | B7 | Estimated 1000-neuron memory footprint |
 | B8 | Brain file growth per new fact |
+| B9 | Single fluent generation |
 
 The committed benchmark report is generated with:
 

BENCHMARKS.md

@@ -6,14 +6,15 @@ Mode: `full`
 
 | ID | Benchmark | Result | Unit | Detail |
 |---|---|---:|---|---|
-| B1 | single teach | 0.0687 | ms/op | 25 iterations |
-| B2 | single ask | 0.0278 | ms/op | 200 iterations |
-| B3 | .manas save | 0.4808 | ms/op | 25 iterations |
-| B4 | .manas load | 0.1639 | ms/op | 50 iterations |
-| B5 | tokenizer 1000 words | 0.3568 | ms/op | 100 iterations |
-| B6 | anti-forgetting proof | 0.3720 | s | single fixed seed |
+| B1 | single teach | 0.0530 | ms/op | 25 iterations |
+| B2 | single ask | 0.0230 | ms/op | 200 iterations |
+| B3 | .manas save | 0.5703 | ms/op | 25 iterations |
+| B4 | .manas load | 0.2349 | ms/op | 50 iterations |
+| B5 | tokenizer 1000 words | 0.5099 | ms/op | 100 iterations |
+| B6 | anti-forgetting proof | 0.5167 | s | single fixed seed |
 | B7 | 1000-neuron footprint | 482.1875 | KiB | estimated heap footprint, total=1000 |
 | B8 | brain growth per fact | 827.2500 | bytes/fact | n=32, min=687, max=5087 |
+| B9 | single generate | 0.0323 | ms/op | 200 iterations |
 
 B7 reports an internal heap-footprint estimate for network-owned buffers and neuron storage, not process RSS.
 

CHANGELOG.md

@@ -9,6 +9,14 @@ Manas uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Next
+
+- Post-v2 release hardening.
+
+---
+
+## [2.0.0] — 2026-07-04
+
 ### Completed
 
 - Stage 0 — Workspace and foundation.
@@ -30,6 +38,7 @@ Manas uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Stage 16 — Benchmarks and test suite.
 - Stage 17 — Layer growth.
 - Stage 18 — Internet refresh agent.
+- Stage 19 — Language generation.
 
 ### Added
 
@@ -108,9 +117,9 @@ Manas uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Added compression tests proving neuron count reduction, frozen-neuron safety,
   high-importance survival, anti-forgetting after compression, dry-run behavior,
   and brain file-size shrinkage.
-- Added the non-runtime `manas-benches` workspace crate with B1-B8 benchmark
-  coverage for teach, ask, save, load, tokenization, anti-forgetting, memory
-  footprint, and brain file growth.
+- Added the non-runtime `manas-benches` workspace crate with B1-B9 benchmark
+  coverage for teach, ask, generate, save, load, tokenization, anti-forgetting,
+  memory footprint, and brain file growth.
 - Added `BENCHMARKS.md` with generated full-run benchmark results.
 - Added Stage 16 integration coverage for the 22-fact demo, anti-forgetting,
   persistence, growth, protection, compression, freshness, and ingestion.
@@ -134,18 +143,20 @@ Manas uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   stale protected memories while `manas ask` remains local-only.
 - Added Stage 18 tests for agent planning/parsing, trainer refresh behavior,
   protected stale refresh, v3 persistence, v2 compatibility, and CLI refresh.
-
-### Next
-
-- Stage 19 — Language generation.
+- Added `manas-language` as a local fluent generation crate built on top of
+  associative-memory query results.
+- Added expanded query decoding for generation while keeping default
+  `manas ask` compact and backward-compatible.
+- Added `manas generate <prompt>`, `manas generate --max-words N`, and
+  `manas ask --fluent <question>` for sentence output generated from neural
+  concepts.
+- Added Stage 19 language and CLI tests proving generation still works after
+  historical sidecars are deleted and still reports `neural weights` as source.
+- Added B9 benchmark coverage for single fluent generation.
 
 ---
 
-<!-- Releases will be added here as stages complete -->
-
-<!--
-
-## [0.1.0] — TBD
+## [0.1.0] — Historical Stage 13 milestone
 
 ### Added
 - Associative memory engine — knowledge stored in neural weights directly
@@ -162,12 +173,10 @@ Manas uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - All v1 sidecar files (brain.manas.sources, brain.manas.sourceindex,
   brain.manas.seq, brain.manas.transformer, brain.manas.langmeta)
 - Text-file-based answering system from v1
-- manas-language crate (transformer path)
+- v1 transformer-path sidecars
 - manas-agent crate
 - manas-memory crate
 
--->
-
 ---
 
 *See [ROADMAP.md](./ROADMAP.md) for planned upcoming changes.*