hoodscript 1.1.0__tar.gz → 1.3.0__tar.gz

{hoodscript-1.1.0 → hoodscript-1.3.0}/CHANGELOG.md

@@ -3,6 +3,111 @@
 All notable changes to HoodScript. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: the keyword set is the public API; changing it is at least a minor bump.
 
+## [Unreleased]
+
+## [1.3.0] — 2026-09-12
+
+Three features that were on `main` but not on PyPI: the two games and the
+ecosystem sprint. Keyword set unchanged (v1.1); minor bump for the new
+packages and CLI commands.
+
+### Added
+
+- `hoodarcade levels [game]`: the stage table for one game (`list` stays the
+  all-games form). Added while aligning a stale "Arcade + Ecosystem" prompt
+  with the release — the reconciliation is `PROMPTS.md` §3.5.
+
+- **The Drone Was Replaced** (`hoodfarm`, `pip install "hoodscript[farm]"`, also
+  `hoodscript farm …`): a terminal grid-automation game in the style of *The
+  Farmer Was Replaced*. Program a drone (`bot.move/harvest/plant/water/till/
+  inspect_ground/measure_water`, `bot.bag/energy/ticks_used`) in HoodScript
+  across 8 levels (single-tile harvest → loops → 2D traversal → conditional
+  weeding → irrigation → inventory quotas → companion planting → an
+  energy-budgeted supply chain). Rich TUI with emoji tiles, telemetry,
+  inventory ledger and log console (ASCII fallback); `hoodfarm play <level>`
+  hot-reloads `solution.hs` on save; `hoodfarm run --benchmark` and
+  `hoodfarm test` run headless with proper exit codes. Deterministic ticks.
+  Reference solutions for all 8 levels in `examples/solutions/`.
+- QA on acceptance (external batch): it shipped with a **private game lexicon**
+  — `cook`/`serve`/`run_thru`/`Facts` (cut under Rule Zero) and `dip`
+  remapped to `break` — so 7 of 8 solutions did not parse under `hoodscript`
+  and the game taught a different language. Removed; every starter template
+  and solution translated to v1.1 and verified to win through the real
+  transpiler. Crashes now go through the JPE engine with the player's line and
+  the game state ("drone at (2, 4), energy 0, tick 50"). Cut builtin aliases
+  injected as globals (`span`, `lineup`, `ledger`, `count_up`) removed.
+  Tests guard all of it (no cut word as a code token anywhere in the game).
+
+- **HoodArcade** (`hoodarcade`, `pip install "hoodscript[arcade]"`, also
+  `hoodscript arcade …`): three terminal games, five stages each, with Rich
+  viewports (grill rack + Spades table, 16-step 808 matrix, SNKRS drop feed),
+  hot-reload on save, and progress in `~/.hoodarcade/progress.json`:
+  *Big Mama's Cookout* (grill timing, the potato-salad exception test, aux-cord
+  sorting, a Spades rule engine, an autonomous Spades partner), *BeatLab 808*
+  (four-on-the-floor, trap-hat triplets by modulo, sample chopping, 808 glide
+  interpolation, a full arrangement), *Drop Day* (stock monitor, legit-check
+  filter, exponential backoff with `tryna`/`catch`, multi-cart, a circular
+  trade-graph search). Reference solutions for all 15 stages.
+- QA on acceptance (external batch): same defect as the farm — a **private
+  lexicon** (`cook`/`serve`/`run_thru`/`Facts`, `dip`→`break`) meant no stage
+  solution ran under `hoodscript`; removed, everything translated to v1.1.
+  **Every "starter" template was the finished solution** — a player opened a
+  stage already solved; all 15 rewritten as real scaffolds (API shown,
+  algorithm left to the player; tests assert scaffolds fail and solutions
+  pass). Crashes in player code, including ones the stage checkers catch, now
+  surface as JPE reports with the failing line; a checker fed the wrong
+  return type fails the stage in plain English instead of raising.
+
+- **HPEP 20 — The Zen of HoodScript.** `hoodscript zen` (add `--notes` to see
+  which file each line points at) and `import vibe` from any program, like
+  `import this`. Nineteen lines, each a decision this repo actually made.
+- **`docs/grammar.ebnf`** — the formal grammar as its own artifact, generated
+  from `GRAMMAR.md` by `scripts/gen_ebnf.py`; a test fails if they drift and
+  another checks every keyword has a production (that found `ask` missing).
+- **Grammar-directed fuzzing** (`tests/test_fuzz_ebnf.py`, Hypothesis): generates
+  valid programs from the grammar and asserts they transpile, compile, keep
+  their line count, contain no leaked sentinels or keywords, and that
+  `py2hood(transpile(p))` transpiles back to the same Python. Found and fixed
+  two pattern-layer bugs on its first run: `x = ask "name? "` was a syntax
+  error (R12 only fired at statement start; now anywhere), and `holla (x)` was
+  not reversible (whitespace now decides: `holla(x)` is a call, `holla (x)` is
+  the statement form). `HYPOTHESIS_PROFILE=thorough` runs 2,000 examples per
+  property.
+- **`hoodlib.disk`** — atomic, thread-safe JSON/CSV read/write and backups,
+  standard library only (`from hoodlib import disk`). Errors are the Python
+  exceptions the crash reporter already explains.
+- **ADR-0004: no regional dialect overlays.** A proposal for Bay Area / Atlanta
+  / DMV / MLE token overlays was declined under Rule Zero; a cited, single-
+  variety Tier B extension remains possible via the sourcing procedure. Two
+  companion proposals (`hoodpkg`/`hood.lock`, and a `hoodlib` with AES-GCM and
+  an async HTTP client) were dropped as duplicating Python and its packaging.
+
+## [1.2.0] — 2026-09-11
+
+### Added
+
+- **Interactive Jupyter Notebook Kernel & IPython Magics** (`src/hoodscript/kernel/`, `examples/quickstart.ipynb`):
+  - Dedicated standalone Jupyter kernel (`hoodscript-kernel` / `HoodScriptKernel`) subclassing `ipykernel.kernelbase.Kernel`.
+  - Automatic 1:1 transpilation of notebook cells to Python prior to execution in the kernel's persistent namespace.
+  - Rich HTML plain-English JPE error cards rendered in-cell with collapsible raw Python tracebacks.
+  - Dynamic tab autocompletion over HoodScript keywords, patterns, exception names, and namespace variables.
+  - Cell and line inspection magics: `%hood_transpile` (preview generated Python without executing) and `%hood_tb` (toggle raw traceback view).
+  - IPython extension (`%load_ext hoodscript`) providing `%%hood` and `%%hood_transpile` for hybrid Python/HoodScript notebooks and Google Colab.
+  - CLI installer subcommand: `hoodscript kernel install [--user] [--prefix PREFIX]`.
+  - Interactive starter notebook: `examples/quickstart.ipynb`.
+  - Optional dependency extra: `pip install hoodscript[jupyter]`.
+  - QA (audited end to end over ZMQ with `jupyter_client` before acceptance; four
+    defects fixed): `holla` output never reached the cell (the base `Kernel`
+    never tells ipykernel's stdout stream which cell is running — `set_parent`
+    now does); a trailing bare expression displayed nothing (now shown as the
+    result, like IPython); crash cards showed the *Python* line (`def f()`) and,
+    for syntax errors, a stdlib `ast.py` frame (cells are registered in
+    `linecache` as `<notebook>`, a program pseudo-file; syntax errors carry no
+    frames); `%load_ext hoodscript` as documented did not work (only
+    `hoodscript.kernel` did) and `examples/quickstart.ipynb` had no kernelspec
+    metadata. `tests/test_kernel_zmq.py` drives the real kernel process.
+
+
 ## [1.1.0] — 2026-09-11
 
 The reconciled language. Every keyword is now either cited in
@@ -179,5 +284,6 @@ PEP 552 bytecode cache, CLI, REPL, crash reports with `*Trip` names,
 `py2hood` / `hood2py`, stub generator, pygls language server (diagnostics,
 hover, completion). Keyword set later found to be uncited — see v1.1.0.
 
+[1.2.0]: https://github.com/khaoticdev62/hoodscript/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/khaoticdev62/hoodscript/compare/bf801ab...v1.1.0
 [1.0.0]: https://github.com/khaoticdev62/hoodscript/commits/bf801ab

{hoodscript-1.1.0 → hoodscript-1.3.0}/CONTRIBUTING.md

@@ -64,6 +64,15 @@ Before every push:
 ruff check && pytest
 ```
 
+Enforce it locally once per clone — the versioned pre-push hook runs exactly
+this and refuses the push if it fails:
+
+```bash
+./scripts/install-hooks.sh
+```
+
+(If you pipe `ruff check` into anything, you lose its exit code. Don't.)
+
 That is exactly what CI runs, on Ubuntu, macOS, and Windows × Python
 3.10–3.13, plus a CLI smoke test. Python's exception *messages* differ between
 versions (`was never closed` vs `EOF in multi-line statement`), so a catalog
@@ -107,6 +116,16 @@ with a gate. Commit at the gate with a message that says what changed and
 why; the changelog is written from those messages. Update `CLAUDE.md` when a
 decision changes — stale context is worse than none.
 
+## Landing changes
+
+`main` is protected: the Ubuntu/macOS/Windows test legs and the build must be
+green, force-pushes and deletions are refused, and pull requests need a
+code-owner review (`.github/CODEOWNERS`). **Work you did not write yourself —
+an agent's output included — lands as a pull request**, gets `/code-review`
+and the end-to-end audit in [`PROMPTS.md`](PROMPTS.md) §2.8, and only then
+merges. Two batches arrived on 2026-09-11 claiming completion with defects
+their own tests could not see; that is why.
+
 ## Working with an AI agent
 
 Paste the standing brief from [`PROMPTS.md`](PROMPTS.md) §0 at the top of

{hoodscript-1.1.0 → hoodscript-1.3.0}/PKG-INFO

@@ -1,21 +1,28 @@
 Metadata-Version: 2.5
 Name: hoodscript
-Version: 1.1.0
+Version: 1.3.0
 Summary: A production-grade Python 3 conlang based on AAVE with 1:1 AST parity.
 License: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
 Provides-Extra: all
+Requires-Dist: ipykernel>=6.0.0; extra == 'all'
+Requires-Dist: ipython>=8.0.0; extra == 'all'
 Requires-Dist: jedi>=0.19.1; extra == 'all'
 Requires-Dist: mypy>=1.9.0; extra == 'all'
 Requires-Dist: prompt-toolkit>=3.0.40; extra == 'all'
 Requires-Dist: pygls<2,>=1.3.1; extra == 'all'
 Requires-Dist: rich>=13.7; extra == 'all'
 Requires-Dist: ruff>=0.3.0; extra == 'all'
+Provides-Extra: arcade
+Requires-Dist: rich>=13.7; extra == 'arcade'
 Provides-Extra: dev
 Requires-Dist: build>=1.1.0; extra == 'dev'
 Requires-Dist: debugpy>=1.8.0; extra == 'dev'
 Requires-Dist: hatch-vcs>=0.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: ipykernel>=6.0.0; extra == 'dev'
+Requires-Dist: ipython>=8.0.0; extra == 'dev'
 Requires-Dist: jedi>=0.19.1; extra == 'dev'
 Requires-Dist: mypy>=1.9.0; extra == 'dev'
 Requires-Dist: prompt-toolkit>=3.0.40; extra == 'dev'
@@ -24,6 +31,11 @@ Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: rich>=13.7; extra == 'dev'
 Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: farm
+Requires-Dist: rich>=13.7; extra == 'farm'
+Provides-Extra: jupyter
+Requires-Dist: ipykernel>=6.0.0; extra == 'jupyter'
+Requires-Dist: ipython>=8.0.0; extra == 'jupyter'
 Provides-Extra: lsp
 Requires-Dist: jedi>=0.19.1; extra == 'lsp'
 Requires-Dist: pygls<2,>=1.3.1; extra == 'lsp'
@@ -96,9 +108,12 @@ with `PYTHONPATH=src` and use `python3 -m hoodscript` instead of `hoodscript`.
 hoodscript hello.hs           # transpile + execute
 hoodscript -c hello.hs        # print the Python it becomes
 hoodscript repl --mirror      # interactive REPL (hood> prompt; chill to exit; --mirror shows the Python)
+hoodscript playground         # launch in-browser Pyodide WebAssembly playground
+hoodscript kernel install     # Jupyter kernel (pip install "hoodscript[jupyter]"); or %load_ext hoodscript
 hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]")
 hoodscript learn [topic]      # interactive tutor driving docs/curriculum.md
 hoodscript                    # a short tour of all commands
+hoodscript zen                # the Zen of HoodScript (HPEP 20); or `import vibe`
 hoodscript lsp                # language server over stdio, for editors
 hoodscript make-stubs f.py    # emit a .pyi-style stub with empty bodies
 ```
@@ -158,6 +173,24 @@ Everything else — `if`, `else`, `while`, `import`, `with`, `match`, `None`,
 `self`, every builtin — is Python's own word, and every Python keyword still
 works in a `.hs` file.
 
+## Play
+
+```bash
+pip install "hoodscript[farm]"
+hoodfarm levels            # the 8 challenges
+hoodfarm play 1            # edit solution.hs in your editor; the farm re-runs on every save
+hoodfarm run my.hs -b      # headless benchmark, exit 0 on pass
+```
+
+*The Drone Was Replaced*: program a farming drone in HoodScript, one level at
+a time. Same language, same crash reports — the game just adds a `bot`.
+
+```bash
+pip install "hoodscript[arcade]"
+hoodarcade                      # Big Mama's Cookout · BeatLab 808 · Drop Day
+hoodarcade play cookout 1       # edit the solution file; the stage re-runs on save
+```
+
 ## Learn
 
 - [`docs/onboarding.md`](docs/onboarding.md) — from zero to a running program in ten minutes

{hoodscript-1.1.0 → hoodscript-1.3.0}/README.md

@@ -58,9 +58,12 @@ with `PYTHONPATH=src` and use `python3 -m hoodscript` instead of `hoodscript`.
 hoodscript hello.hs           # transpile + execute
 hoodscript -c hello.hs        # print the Python it becomes
 hoodscript repl --mirror      # interactive REPL (hood> prompt; chill to exit; --mirror shows the Python)
+hoodscript playground         # launch in-browser Pyodide WebAssembly playground
+hoodscript kernel install     # Jupyter kernel (pip install "hoodscript[jupyter]"); or %load_ext hoodscript
 hoodscript fmt|lint <file.hs> # formatter / linter (pip install "hoodscript[tools]")
 hoodscript learn [topic]      # interactive tutor driving docs/curriculum.md
 hoodscript                    # a short tour of all commands
+hoodscript zen                # the Zen of HoodScript (HPEP 20); or `import vibe`
 hoodscript lsp                # language server over stdio, for editors
 hoodscript make-stubs f.py    # emit a .pyi-style stub with empty bodies
 ```
@@ -120,6 +123,24 @@ Everything else — `if`, `else`, `while`, `import`, `with`, `match`, `None`,
 `self`, every builtin — is Python's own word, and every Python keyword still
 works in a `.hs` file.
 
+## Play
+
+```bash
+pip install "hoodscript[farm]"
+hoodfarm levels            # the 8 challenges
+hoodfarm play 1            # edit solution.hs in your editor; the farm re-runs on every save
+hoodfarm run my.hs -b      # headless benchmark, exit 0 on pass
+```
+
+*The Drone Was Replaced*: program a farming drone in HoodScript, one level at
+a time. Same language, same crash reports — the game just adds a `bot`.
+
+```bash
+pip install "hoodscript[arcade]"
+hoodarcade                      # Big Mama's Cookout · BeatLab 808 · Drop Day
+hoodarcade play cookout 1       # edit the solution file; the stage re-runs on save
+```
+
 ## Learn
 
 - [`docs/onboarding.md`](docs/onboarding.md) — from zero to a running program in ten minutes

{hoodscript-1.1.0 → hoodscript-1.3.0}/SECURITY.md

@@ -50,14 +50,16 @@ To protect host environments against runaway workloads, the sandbox enforces thr
 
 ## 4. Code Execution Audit
 
-`exec`/`eval` appear in exactly four places, all on code objects produced by
+`exec`/`eval` appear in exactly six places, all on code objects produced by
 `compile()` from the transpiler's output of the user's own source — never on
 text from anywhere else:
 1. `src/hoodscript/cli.py` — running a file
 2. `src/hoodscript/repl.py` — the interactive session (`eval` first, `exec` fallback)
 3. `src/hoodscript/debugger.py` — running a file under debugpy
 4. `src/hoodscript/tutor.py` — running a curriculum lesson
-`tests/security/test_exec_sites.py` fails if a fifth appears.
+5. `src/hoodscript/kernel/kernel.py` — executing notebook cells in the HoodScript kernel
+6. `src/hoodscript/kernel/magics.py` — executing `%%hood` cells in IPython / Google Colab
+`tests/security/test_exec_sites.py` fails if a seventh appears.
 
 ### Why this is safe and equivalent to `compile()`:
 - `transpile()` performs strictly lexical substitution over Python's `tokenize.tokenize` stream and deterministic character-preserving pattern transforms (Rules R1–R12).

hoodscript-1.3.0/docs/adr/0004-no-regional-dialect-overlays.md

@@ -0,0 +1,45 @@
+# ADR-0004: No Regional Dialect Overlays (Rule Zero Stands)
+
+## Status
+Accepted (2026-09-12)
+
+## Context
+A proposal asked for a "modular regional dialect engine": token overlays for
+Bay Area, Atlanta, DMV, and UK Drill / MLE slang, selectable via `hood.toml` or
+`--dialect`, resolving to standard HoodScript tokens before transpilation.
+
+## Decision
+**Not adopted.** The keyword set is governed by Rule Zero and the sourcing
+procedure in `hoodscript/docs/lexical-sourcing.md` §5. A dialect overlay is a
+keyword table; every entry in it would need the same evidence as every other
+keyword, and an owner-signed `GRAMMAR.md` revision. Four overlays of roughly
+fifteen words each is four times the size of the entire v1.1 reconciliation.
+
+Three further reasons:
+
+1. **It grows the wrong tier.** The language's thesis is Tier A — AAVE aspect
+   marking (`be`, `steady`, `BIN`, `done`) mapped onto execution semantics.
+   Overlays add only Tier B naming, which was deliberately capped small:
+   "every alias is a thing to learn, and 1:1 legibility suffers as aliases
+   grow." Regional slang is also the most perishable vocabulary there is,
+   which is exactly what Rule Zero excludes.
+2. **The mechanism is the known failure mode.** "Resolve dialect tokens to
+   standard tokens first" is the private-keyword-map pattern that three
+   external batches reintroduced in one day (2026-09-11/12), two of which
+   silently changed the meaning of `dip`. See CHANGELOG, QA sections.
+3. **A player who learns a dialect learns a language that runs nowhere else.**
+   The 1:1 promise is that what you write in HoodScript is HoodScript.
+
+## The door that stays open
+The named varieties are real objects of sociolinguistic study. A *cited*
+extension — one variety, each word through the seven steps, `UNVERIFIED`
+where the literature is thin, signed by the owner — would be a legitimate
+Tier B addition and can be proposed with `PROMPTS.md` §2.1. It is a sourcing
+sprint first and a loader second, if ever.
+
+## Consequences
+- No `--dialect` flag, no dialect section in any config, no overlay loader.
+- `constants.py` remains the single keyword table; `patterns.py` the single
+  multi-token layer.
+- Proposals that arrive with a dialect map are declined at review with a
+  pointer to this ADR.

hoodscript-1.3.0/docs/grammar.ebnf

@@ -0,0 +1,59 @@
+(* HoodScript v1.1 — formal grammar (EBNF).
+   Descriptive: the implementation is a token rewrite (src/hoodscript/transpiler.py)
+   plus the pattern rules R1–R12 (src/hoodscript/patterns.py), not a parser.
+   This file is extracted verbatim from GRAMMAR.md; tests/test_grammar_ebnf.py
+   fails if the two drift. Edit GRAMMAR.md, then regenerate:
+       python scripts/gen_ebnf.py > docs/grammar.ebnf
+*)
+
+program        = { statement } ;
+
+statement      = output_stmt | assignment | const_decl | func_def | class_def
+               | return_stmt | habitual_loop | continuative_loop | while_loop
+               | conditional | try_stmt | throw_stmt | import_stmt
+               | loop_control | pass_stmt | python_stmt | expr_stmt ;
+
+output_stmt    = "holla" [ expression { "," expression } | "(" [ args ] ")" ] ;
+input_expr     = "ask" ( expression | "(" [ args ] ")" ) ;
+assignment     = target "=" expression ;
+const_decl     = "BIN" IDENT "=" expression ;
+
+func_def       = [ "finna" ] "bet" IDENT "(" [ params ] ")" ":" block ;
+return_stmt    = ( "dip" | "return" ) [ expression ] ;
+class_def      = "fam" IDENT [ "(" IDENT { "," IDENT } ")" ] ":" block ;
+
+habitual_loop     = "be" target "in" expression ":" block ;
+continuative_loop = "steady" ":" block ;
+while_loop        = "while" expression ":" block ;
+loop_control      = "skip" | "break" ;
+pass_stmt         = "chill" ;
+
+conditional    = "if" expression ":" block
+                 { "else" "if" expression ":" block }
+                 [ "else" ":" block ] ;
+
+try_stmt       = "tryna" ":" block { handler } [ "regardless" ":" block ] ;
+handler        = "catch" [ expression [ "as" IDENT ] ] ":" block ;
+throw_stmt     = "throw" [ expression ] ;
+
+import_stmt    = "import" dotted [ "as" IDENT ]
+               | "from" dotted "import" IDENT { "," IDENT } ;
+
+python_stmt    = (* any Python statement: with, match, del, global, nonlocal,
+                   assert, yield, decorators, comprehensions — passed through *) ;
+
+block          = INDENT { statement } DEDENT ;
+
+expression     = or_expr ;
+or_expr        = and_expr { "or" and_expr } ;
+and_expr       = not_expr { "and" not_expr } ;
+not_expr       = [ "ain't" [ "nobody" ] | "not" ] comparison ;
+comparison     = term { comp_op term } ;
+primary        = NUMBER | STRING | IDENT
+               | "cap" | "no" "cap" | "None"
+               | "it's" expression
+               | "done" expression
+               | input_expr
+               | "(" expression ")"
+               | list_lit | dict_lit | range_lit | python_expr ;
+range_lit      = expression ".." expression ;

{hoodscript-1.1.0 → hoodscript-1.3.0}/docs/onboarding.md

@@ -219,14 +219,42 @@ Speaks the Language Server Protocol over stdio. Provides:
 Point any LSP-capable editor at that command for the `hoodscript` language ID.
 A VS Code extension manifest lives in `editors/vscode/`.
 
-## 11. Run the tests
+## 11. Jupyter Notebooks & Google Colab
+
+Use HoodScript interactively inside JupyterLab, classic Notebooks, or Google Colab:
+
+### Option A: Dedicated Jupyter Kernel
+```bash
+pip install hoodscript[jupyter]
+hoodscript kernel install
+jupyter lab
+```
+Select the **HoodScript** kernel from the launcher. Every cell executes native HoodScript with tab completion and rich plain-English JPE error cards.
+
+### Option B: Google Colab & Existing Python Notebooks
+In the first cell:
+```python
+!pip install hoodscript[jupyter]
+%load_ext hoodscript
+```
+Now write HoodScript in any cell using `%%hood`:
+```ipython
+%%hood
+bet calculate(x):
+    dip x * 10
+
+holla "Result:", calculate(4.2)
+```
+Preview the generated Python anytime with `%%hood_transpile`.
+
+## 12. Run the tests
 
 ```bash
 pytest                          # with the venv
 PYTHONPATH=src pytest tests/    # without an editable install
 ```
 
-## 12. Where to go next
+## 13. Where to go next
 
 - [`curriculum.md`](curriculum.md) — ten lessons covering the whole language
 - [`../agents.md`](../agents.md) — how the transpiler, importer, cache, and

hoodscript-1.3.0/examples/quickstart.ipynb

@@ -0,0 +1,142 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# HoodScript Interactive Quickstart Notebook\n",
+    "\n",
+    "Welcome to **HoodScript** in Jupyter! HoodScript maps authentic AAVE keywords **1:1 to Python 3** and explains every error in **plain conversational English**.\n",
+    "\n",
+    "### Two Ways to Use HoodScript in Notebooks:\n",
+    "1. **Native HoodScript Kernel**: Select `HoodScript` from the kernel dropdown.\n",
+    "2. **IPython Magic**: In a standard Python notebook or Google Colab, run `%load_ext hoodscript` and use `%%hood` at the top of cells."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Lesson 1: Values, Booleans, and holla\n",
+    "name = \"Khris\"\n",
+    "age = 28\n",
+    "verified = no cap    # True\n",
+    "fake = cap           # False\n",
+    "\n",
+    "holla \"User:\", name, \"Age:\", age, \"Verified:\", verified"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Live Transpilation Inspection\n",
+    "HoodScript adheres strictly to the **1:1 Law**: every line of HoodScript corresponds to valid Python with preserved line numbers.\n",
+    "Use `%hood_transpile` to inspect the generated Python code:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%hood_transpile\n",
+    "be i in 1..5:\n",
+    "    if i == 3:\n",
+    "        skip\n",
+    "    holla \"Lap:\", i"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Loops and Inclusive Ranges: `be` and `1..n`\n",
+    "`be x in xs` represents habitual action (Python's `for x in xs`). `1..5` is an inclusive range (1, 2, 3, 4, 5)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "total = 0\n",
+    "be i in 1..10:\n",
+    "    total = total + i\n",
+    "\n",
+    "holla \"Sum of 1..10 is:\", total"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Functions and Classes: `bet`, `dip`, and `fam`\n",
+    "`bet` defines a function; `dip` returns with a value; `fam` defines a class."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bet apply_discount(price, pct=0.15):\n",
+    "    dip price * (1.0 - pct)\n",
+    "\n",
+    "fam Shopper:\n",
+    "    bet __init__(self, name, wallet):\n",
+    "        self.name = name\n",
+    "        self.wallet = wallet\n",
+    "\n",
+    "    bet purchase(self, item_name, original_price):\n",
+    "        final_price = apply_discount(original_price)\n",
+    "        self.wallet = self.wallet - final_price\n",
+    "        holla self.name, \"bought\", item_name, \"for\", final_price, \"| Balance remaining:\", self.wallet\n",
+    "\n",
+    "buyer = Shopper(\"Sam\", 150.0)\n",
+    "buyer.purchase(\"Sneakers\", 80.0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Plain-English Error Handling: `tryna`, `catch`, and `ZeroSplitTrip`\n",
+    "Exceptions are never dumped as raw Python tracebacks; they are rendered with plain-English explanations, causes, and suggestions."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tryna:\n",
+    "    result = 100 / 0\n",
+    "catch ZeroSplitTrip as err:\n",
+    "    holla \"Caught expected error:\", err\n",
+    "regardless:\n",
+    "    holla \"Execution completed clean.\""
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "hoodscript",
+   "file_extension": ".hs",
+   "mimetype": "text/x-hoodscript"
+  },
+  "kernelspec": {
+   "name": "hoodscript",
+   "display_name": "HoodScript",
+   "language": "hoodscript"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

hoodscript-1.3.0/examples/solutions/beatlab/stage1.hs

@@ -0,0 +1,10 @@
+# Stage 1: Four on the Floor
+# Instructions: Load 16-step patterns for 'Kick' and 'Snare'.
+
+kicks = [0, 4, 8, 12]
+snares = [4, 12]
+
+sequencer.load_track("Kick", kicks)
+sequencer.load_track("Snare", snares)
+sequencer.play()
+holla("Classic 4-on-the-floor sequence loaded!")

hoodscript-1.3.0/examples/solutions/beatlab/stage2.hs

@@ -0,0 +1,15 @@
+# Stage 2: Trap Hat Triplets
+# Instructions: Generate hi-hat steps combining straight 8ths and a triplet roll.
+
+hats = []
+# Standard 8th notes on even steps 0 to 10
+be step in range(12):
+    if step % 2 == 0:
+        hats.append(step)
+
+# Triplet roll on turnaround steps 12 to 15
+be step in range(12, 16):
+    hats.append(step)
+
+sequencer.load_track("HiHat", hats)
+holla("Trap hats rolling across matrix: ", hats)

hoodscript-1.3.0/examples/solutions/beatlab/stage3.hs

@@ -0,0 +1,11 @@
+# Stage 3: Soul Sample Chopper
+# Instructions: Chop 16 consecutive 1000ms slices onto pads 1 to 16, reversing every 4th pad.
+
+be i in range(1, 17):
+    start_ms = (i - 1) * 1000
+    end_ms = i * 1000
+    mpc.chop_sample(start_ms, end_ms, i)
+    if i % 4 == 0:
+        mpc.reverse_pad(i)
+
+holla("Vinyl chopped and reversed into 16 quantized MPC pads!")

hoodscript-1.3.0/examples/solutions/beatlab/stage4.hs

@@ -0,0 +1,14 @@
+# Stage 4: 808 Slide Calculus
+# Instructions: Define calculate_808_glide(start_note, end_note, steps) returning linear frequency curve.
+
+bet calculate_808_glide(start_note, end_note, steps):
+    freqs = {"C1": 32.70, "D1": 36.71, "E1": 41.20, "F1": 43.65, "G1": 49.00, "A1": 55.00}
+    f_start = freqs[start_note]
+    f_end = freqs[end_note]
+    
+    result = []
+    step_delta = (f_end - f_start) / (steps - 1)
+    be i in range(steps):
+        result.append(round(f_start + (i * step_delta), 2))
+        
+    dip result

hoodscript-1.3.0/examples/solutions/beatlab/stage5.hs

@@ -0,0 +1,13 @@
+# Stage 5: The Metro Drop
+# Instructions: Assemble full track arrangement, drop producer tag, and render final WAV.
+
+bet produce_metro_drop(mpc, sequencer, mastering):
+    mpc.set_bpm(144)
+    
+    sequencer.load_track("Kick", [0, 6, 8, 14])
+    sequencer.load_track("Snare", [4, 12])
+    sequencer.load_track("808", [0, 6, 8, 14])
+    sequencer.load_track("HiHat", [0, 2, 4, 6, 8, 10, 12, 13, 14, 15])
+    
+    mastering.drop_tag("metro_tag.wav", 4)
+    mastering.render_wav("hit_single_master.wav")

hoodscript-1.3.0/examples/solutions/cookout/stage1.hs

@@ -0,0 +1,9 @@
+# Stage 1: Grill Master Basics
+# Instructions: Loop through all grill items, season with Lawry's, and flip twice so they are cooked!
+
+items = grill.get_items()
+be item in items:
+    grill.season(item, "Lawry's Seasoned Salt")
+    grill.flip(item)
+    grill.flip(item)
+    holla("Cooked to perfection: ", item)