docs: strengthen quickstart and contribution paths

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,35 @@
+name: Bug report
+description: Report a reproducible issue in Nano's compiler, IR, runtime, or bridge.
+title: "[bug]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please do not include secrets, private market data, or security-sensitive details. Use SECURITY.md for a vulnerability report.
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include a small .nano source, IR, MarketFrame, and traceback or result where possible.
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Nano version or commit
+      placeholder: 0.1.0 or a commit SHA
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/DBarr3/Nano/security/advisories/new
+    about: Please report security-sensitive issues privately.

.github/ISSUE_TEMPLATE/language-change.yml

@@ -0,0 +1,52 @@
+name: Language or IR proposal
+description: Propose a focused change to Nano syntax, IR, or reference-runtime behavior.
+title: "[language]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Nano is intentionally small. Explain the problem first, then show how the proposal preserves deterministic reference execution and the host-owned decision boundary.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: Describe the concrete limitation or user need.
+    validations:
+      required: true
+  - type: textarea
+    id: syntax
+    attributes:
+      label: Proposed .nano syntax
+      description: Show a minimal before/after example.
+      render: nano
+    validations:
+      required: true
+  - type: textarea
+    id: ir
+    attributes:
+      label: Strategy IR impact
+      description: Show the expected JSON shape or explain why the existing IR remains sufficient.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: semantics
+    attributes:
+      label: Determinism and replay semantics
+      description: Explain inputs, ordering, scheduling, and how two identical graph/frame inputs retain the same reference result.
+    validations:
+      required: true
+  - type: textarea
+    id: boundary
+    attributes:
+      label: Host and gate boundary
+      description: Explain data ownership, policy ownership, and why the proposal cannot bypass a host DecisionGate.
+    validations:
+      required: true
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: Compatibility, tests, and documentation
+      description: Note migration/versioning impact and the tests/docs that must change.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/strategy-library.yml

@@ -0,0 +1,69 @@
+name: Strategy library proposal
+description: Propose a well-specified trading strategy for Nano's paired source/IR library.
+title: "[strategy]: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping grow the Nano strategy library. A strategy proposal describes a signal contract for a host to provide; it is not investment advice or a request for live execution.
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      options:
+        - momentum
+        - mean_reversion
+        - trend
+        - volatility
+        - volume
+        - risk
+        - new category proposal
+    validations:
+      required: true
+  - type: input
+    id: name
+    attributes:
+      label: Proposed strategy name
+      description: Use a concise, lowercase_snake_case name for the future file pair.
+      placeholder: rsi_oversold_reversal
+    validations:
+      required: true
+  - type: textarea
+    id: thesis
+    attributes:
+      label: Strategy thesis
+      description: Explain the trading idea in plain language and the intended timeframe.
+    validations:
+      required: true
+  - type: textarea
+    id: signals
+    attributes:
+      label: Host signal contract
+      description: For every signal, give its formula/data source, unit or range, normalization, lookback convention, and threshold direction.
+      placeholder: "RSI(14): host-computed RSI, 0-100; emit only when RSI < 30."
+    validations:
+      required: true
+  - type: textarea
+    id: proposed_source
+    attributes:
+      label: Proposed Nano source
+      description: Draft a v0.1-compatible strategy, if possible. Nano currently supports one schedule, one rule, AND-chained conditions, and five intent actions.
+      render: nano
+  - type: textarea
+    id: intent
+    attributes:
+      label: Proposed intent
+      description: State the action, asset convention, and confidence (if any) the strategy should emit.
+    validations:
+      required: true
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Proposal checklist
+      options:
+        - label: I understand that Nano emits intents and does not place trades or provide investment advice.
+          required: true
+        - label: I will include paired .nano and _ir.json files plus documented signal conventions in a pull request.
+          required: true
+        - label: I will run python -m pytest tests/test_library.py -q before requesting review.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Why does this change belong in Nano?
+
+<!-- Describe the user problem, design rationale, or strategy thesis. -->
+
+## What changed?
+
+<!-- Summarize the implementation and documentation changes. -->
+
+## Validation
+
+- [ ] Focused tests passed.
+- [ ] `python -m pytest -q` passed.
+- [ ] Documentation and examples match the shipped behavior.
+
+## Boundary check
+
+- [ ] The change preserves deterministic reference execution for identical graph/frame inputs.
+- [ ] The change does not bypass the host-owned `DecisionGate` or add external actuation to Nano source/runtime.
+- [ ] If this adds a strategy, it includes paired `.nano` and `_ir.json` files plus documented host signal conventions.

.github/workflows/ci.yml

@@ -41,10 +41,10 @@ jobs:
 
           wheel = next(Path("dist").glob("*.whl"))
           expected = {
-              "nano/examples/momentum.nano",
-              "nano/examples/momentum_ir.json",
-              "nano/library/momentum/rsi_oversold_reversal.nano",
-              "nano/library/momentum/rsi_oversold_reversal_ir.json",
+              path.as_posix()
+              for root in (Path("nano/examples"), Path("nano/library"))
+              for path in root.rglob("*")
+              if path.suffix in {".nano", ".json"}
           }
           with ZipFile(wheel) as archive:
               packaged = set(archive.namelist())

CONTRIBUTING.md

@@ -1,73 +1,85 @@
 # Contributing to Nano
 
-Thanks for your interest. Nano is a research preview moving fast — contributions that fit the
-project's discipline (deterministic, tested, honestly labeled) are very welcome.
+Welcome. Nano is an alpha reference implementation, and its best contributions make the small language more useful without making its contract less clear. Quant researchers, application engineers, and documentation contributors all have a meaningful place here.
+
+## Start here
+
+| If you want to… | Start with… |
+| --- | --- |
+| Translate a familiar trading idea | [Add a strategy](#add-a-strategy) |
+| Suggest grammar, IR, or runtime behavior | [Open a language proposal](https://github.com/DBarr3/Nano/issues/new?template=language-change.yml) |
+| Report a reproducible defect | [Open a bug report](https://github.com/DBarr3/Nano/issues/new?template=bug-report.yml) |
+| Improve an explanation or correct a claim | A focused documentation issue or pull request |
+
+For security-sensitive reports, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
 
 ## Development setup
 
 ```bash
 git clone https://github.com/DBarr3/Nano.git
 cd Nano
-python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -e ".[dev]"
-python -m pytest tests -q
+python -m venv .venv
+```
+
+Activate the environment:
+
+```bash
+# macOS/Linux
+source .venv/bin/activate
+
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
 ```
 
-Python 3.10+. The whole suite runs in under two seconds — run it constantly.
+Then install and test:
 
-## Where help is most valuable
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
 
-**Easiest entry: the strategy library.** Add a classic quant strategy to
-[`nano/library/`](nano/library/) as `.nano` source plus its expected IR JSON. The library
-README documents the format and the conformance rule (source must compile to the expected IR
-bit-for-bit). This teaches you the whole pipeline in one PR.
+Python 3.10+ is required. The reference suite is intentionally fast; run it often.
 
-**The conformance corpus.** New `.nano` programs in [`nano/examples/`](nano/examples/) that
-exercise untested language shapes — each is source + hand-written IR that must match exactly.
+## Add a strategy
 
-**The CLI.** `nano compile` / `nano replay` / `nano visualize` are designed but not built.
-See [BUILD_ORDER.md](BUILD_ORDER.md) for the intended shape.
+The [strategy library](nano/library/README.md) is the easiest way to learn and extend Nano. Every strategy is a paired artifact: readable `.nano` source plus checked-in IR that the suite must reproduce exactly.
 
-**Docs and papers.** Anything in [`docs/papers/`](docs/papers/) that is unclear, overstated,
-or wrong — issues and PRs both welcome. The house rule: every claim cites shipped code or is
-labeled design/roadmap/research.
+1. Open a [strategy proposal](https://github.com/DBarr3/Nano/issues/new?template=strategy-library.yml) for a new idea or use an existing issue.
+2. Choose one existing category in `nano/library/`, then add `<slug>.nano` and `<slug>_ir.json`.
+3. Document the signal contract in `//` comments: formula or data source, unit/range, any normalization, and the lookback convention the host must supply.
+4. Generate the expected IR with `compile_to_dict()` and keep it formatted like neighboring entries.
+5. Run `python -m pytest tests/test_library.py -q`, then the full suite before opening the pull request.
 
-## Architecture in one diagram
+Nano v0.1 has one schedule and one rule per strategy, AND-chained numeric conditions, and five intent actions. The host supplies every signal and still owns every real-world action. See the [language reference](docs/language.md) before designing a new strategy shape.
 
-```
-.nano source ──► Compiler (nano/compiler/) ──► Nano IR (nano/ir/)
-                                                    │
-                     ┌──────────────────────────────┤
-                     ▼                              ▼
-        Interpreter (nano/runtime/)     Bridge + gate (nano/bridge/)
-        pure, deterministic             intents → your risk engine
-                     │                              │
-                     └──────── append-only audit log┘
-```
+For a normal strategy addition, the library tests automatically discover the source/IR pair and verify compilation, validation, and replay. Add a focused fire/no-fire test only when the new example covers a meaningful runtime edge not already represented.
+
+## Propose a language change
+
+Start with the [language proposal form](https://github.com/DBarr3/Nano/issues/new?template=language-change.yml) before writing an implementation. It asks for the problem, proposed syntax, IR impact, deterministic/replay semantics, host-gate impact, and migration story.
 
-Supporting layers: pattern memory (`nano/memory/`), editor services (`nano/aethercode/`),
-optimization loop (`nano/loop/`). Build sequence and rationale: [BUILD_ORDER.md](BUILD_ORDER.md).
+This discipline matters: Nano's boundary is intentional. Do not add ambient I/O, an external-actuation primitive, a clock/RNG dependency, or a behavior that lets source bypass the host `DecisionGate`.
 
 ## Ground rules
 
-1. **Determinism is non-negotiable.** No ambient clock, RNG, network, or global mutable state
-   anywhere in the IR, compiler, or runtime paths. Time and entropy are injected inputs.
-2. **Programs propose; gates decide.** Never add an actuation primitive to the language or a
-   side-effecting call to the runtime. If your feature needs an effect, it goes through the
-   intent/gate boundary.
-3. **Tests first-class.** New behavior ships with tests; conformance examples must replay
-   bit-identically. `python -m pytest tests -q` must pass before any PR.
-4. **Honest labeling.** Docs distinguish shipped / design / roadmap / research. Don't promote
-   a claim past its evidence.
+1. **Determinism is non-negotiable.** The reference compiler and runtime do not read an ambient clock, RNG, network, or mutable global state.
+2. **Programs propose; gates decide.** Nano emits intents. The host owns policy, persistence, and any external effect.
+3. **Tests travel with behavior.** New behavior, examples, and bug fixes include focused coverage; a library pair must compile to its expected IR and replay deterministically.
+4. **Documentation is part of the contract.** Label shipped behavior, experiments, and research honestly. Do not promote a claim past its evidence.
+5. **Keep changes reviewable.** Prefer one clear reason per pull request and leave a concise record of why the change belongs in Nano.
 
 ## Pull requests
 
-- Branch from `main`; keep PRs focused and small.
-- Commit style: `<type>: <description>` (feat, fix, refactor, docs, test, chore).
-- Describe *why*, not just what. Link the paper or BUILD_ORDER milestone your change serves
-  if one applies.
+- Branch from `main`; keep pull requests focused and small.
+- Use concise commit subjects such as `feat: add strategy fixture` or `docs: clarify signal contract`.
+- Complete the pull-request template, including validation and the relevant boundary checks.
+- For a strategy, include the source, expected IR, signal comments, and test result together.
 
-## Questions and ideas
+## Useful references
 
-Open a GitHub issue — design discussion is welcome, and "this paper's argument doesn't hold
-because…" is a first-class contribution.
+- [Quick-start demo](examples/momentum_demo.py)
+- [Strategy library](nano/library/README.md)
+- [Language reference](docs/language.md)
+- [Architecture](docs/architecture.md)
+- [Status and maturity](docs/status.md)
+- [Security policy](SECURITY.md)