Sync with GitHub, license metadata from LICENSE files, commercial license notice

metadata license: None -> other (snapkitty-tri-license)
README: License section appended
README: GitHub source link added

README.md

@@ -1,162 +1,184 @@
-# MACROGROK — AGC-Inspired Fixed-Point Macro-Model
-
-Patent Pending — BEL ESPRIT D ACCORD TRUST HOLDINGS INC.
-
-Extremely constrained, narrow-task models for 15-bit / Qm.n environments. Code lives in ROM, state in ~2K erasable words. Every bit is budgeted.
-
-## 1. Model Purpose & Scope
-
-* Single, narrowly defined task: attitude correction, trajectory offset, binary/multi-class decision, low-dimensional control law.
-* No general-purpose LM or large feature spaces.
-* Input/output dimensions very small (typically ≤ 8–16).
-
-## 2. Numeric Representation
-
-* Word: 15-bit data (modern 16-bit with 1-bit reserved).
-* Fixed-point Qm.n (e.g., Q1.14, Q3.12, Q7.8) chosen per variable, scale documented per quantity.
-* Double/triple precision only where required.
-* Saturation handling: clamp, wrap, or flag — defined per variable.
-
-## 3. Memory Layout
-
-**Erasable (RAM) — ~2K words target:**
-State vector, input buffer, accumulators, flags/mode bits, tiny stack.
-
-**Fixed (ROM) — majority:**
-Model constants (weights/biases, lookup tables, scale factors), code/macros, pre-computed coefficients. Bank/segment switching optional.
-
-## 4. Core Data Structures
-
-```
-STATE  : fixed-point vector (persistent)
-INPUT  : fixed-point vector (current observation)
-OUTPUT : fixed-point vector or discrete command
-ACC    : accumulator(s) — single/double precision
-SCALES : constant scale factors
-FLAGS  : mode, validity, saturation bits
-```
-
-## 5. Macro Routine Categories
-
-`LOAD_INPUT` / `SCALE_INPUT` · `MATVEC_TINY` / `DOT_PRODUCT_FIXED` (unrolled) · `LOOKUP_SEGMENT` / `PIECEWISE_LINEAR` · `ACTIVATE` (clip/ReLU/threshold) · `UPDATE_STATE` · `NORMALIZE`/`RESCALE` · `SATURATE` · `EMIT_OUTPUT`
-
-Macros expand to shifts, adds, MUL16, and table lookups — no floating point.
-
-## 6. Forward Pass
-
-```
-1. Acquire and scale input → INPUT
-2. Optional tiny feature transform
-3. Core block(s) (mat-vec + nonlinearity, macro-expanded)
-4. State update (if recurrent)
-5. Output scaling + saturation
-6. Write command / flags
-```
-
-All steps use fixed-point ops and explicit erasable temporaries.
-
-## 7. Initialization
-
-Weights/biases/tables in fixed storage; init routine copies needed values to erasable once. Constants never modified at runtime.
-
-## 8. Executive Wrapper (Optional)
-
-Cyclic/priority executive, ability to skip non-critical sections under pressure, watchdog/validity flags.
-
-## 9. Documentation Requirement
-
-For every variable and macro: Qm.n format, physical units, scale, valid range, overflow behavior, memory location (erasable bank or fixed address).
-
-## 10. Example Skeleton
-
-```
-; FIXED (ROM)
-WEIGHTS_Q3_12 ...
-BIAS_Q3_12 ...
-SCALE_IN ...  SCALE_OUT ...
-
-; ERASABLE (RAM)
-STATE DS 4 ; Q3.12
-INPUT DS 4
-OUTPUT DS 2
-ACC DS 2 ; double precision
-
-; MACROS
-MACRO DOT4 ; 4-element dot
-MACRO SAT_Q3_12
-MACRO UPDATE_STATE
-
-INFER
-    LOAD_INPUT
-    SCALE_INPUT
-    DOT4 WEIGHTS_Q3_12, INPUT, ACC
-    ADD BIAS
-    SAT_Q3_12
-    UPDATE_STATE
-    SCALE_OUTPUT
-    STORE OUTPUT
-    RETURN
-```
-
-## Design Principles
-
-Every bit budgeted — tables + interpolation over general arithmetic — unrolled tiny loops — minimal contiguous mutable state — specialized routine, not general engine.
-
----
-
-## Fixed-Point Contract (INFER4 Example)
-
-4-input binary decision, Q format per quantity, saturate to 32-bit ACC.
-
-| Symbol | Format | Role | Overflow |
-|---|---|---|---|
-| `INPUT[4]` | Q1.14 | sensors [-1,1) | clamp |
-| `WEIGHTS[4]` | Q1.14 | ROM coefficients | const |
-| `BIAS` | Q3.12 | offset | const |
-| `ACC` | Q7.24 32-bit | dot accumulator | saturate |
-| `STATE` | Q3.12 | smoothed output | clamp |
-| `OUTPUT` | Q1.14 | command | clamp |
-| `FLAGS` | bits | validity/sat/decision | — |
-
-Q1.14 * Q1.14 → Q2.28 → >>4 → Q3.24 (4 products in 32-bit), >>12 → Q3.12 + `BIAS`.
-
-## Memory Map
-
-```
-; FIXED / ROM
-WEIGHTS_Q1_14: DC 2458, -1638, 819, 3277
-BIAS_Q3_12: DC -256
-ALPHA_Q1_14: DC 12288 ; 0.75
-ONE_Q1_14: DC 16384
-OUT_MIN_Q1_14: DC -16384
-OUT_MAX_Q1_14: DC 16383
-SCORE_MIN_Q3_12: DC -8192 ; -2.0 Q3.12
-SCORE_MAX_Q3_12: DC 8191  ; +2.0
-
-; ERASABLE / RAM
-INPUT: DS 4
-STATE: DS 1 ; Q3.12
-OUTPUT: DS 1
-ACC_HI: DS 1 ; 32-bit hi
-ACC_LO: DS 1 ; 32-bit lo
-TMP0: DS 1
-TMP1: DS 1
-FLAGS: DS 1
-FLAG_VALID=0001  FLAG_SAT=0002  FLAG_POSITIVE=0004
-```
-
-## Primitive Macros
-
-See `examples/infer4.asm` for full `CLR_ACC`, `MAC_Q1_14` (preserves `PROD_HI:PROD_LO` before `ADD32`), `ACC_TO_Q3_12`, `SAT_Q3_12`, `DOT4_Q1_14`, `THRESHOLD_Q3_12` (+1.0/-1.0), `UPDATE_STATE_3_4` (`(3*STATE+TARGET)/4`).
-
-## INFER4 Routine
-
-`examples/infer4.asm` — `INFER4: CLR FLAGS → DOT4 → ACC_TO_Q3_12 → ADD BIAS → SAT → THRESHOLD → UPDATE_STATE_3_4 → OUTPUT=STATE → FLAG_VALID → RET`
-
-Simulator: `python src/sim.py` (Q1.14/Q3.12 fixed-point, matches assembly semantics).
-
-## References
-
-[1] Virtual AGC Manual — ibiblio.org/apollo/assembly_language_manual.html
-[2] AGC — Wikipedia
-[3] Block II: 2048 erasable + 36864 fixed words, 15 data bits + parity
+---
+license: other
+license_name: snapkitty-tri-license
+license_link: https://huggingface.co/Snapkitty/MACROGROK/blob/main/LICENSE.tri
+tags:
+- snapkitty
+---
+
+> Source: [github.com/SNAPKITTYWEST/MACROGROK](https://github.com/SNAPKITTYWEST/MACROGROK)
+
+# MACROGROK — AGC-Inspired Fixed-Point Macro-Model
+
+Patent Pending — BEL ESPRIT D ACCORD TRUST HOLDINGS INC.
+
+Extremely constrained, narrow-task models for 15-bit / Qm.n environments. Code lives in ROM, state in ~2K erasable words. Every bit is budgeted.
+
+## 1. Model Purpose & Scope
+
+* Single, narrowly defined task: attitude correction, trajectory offset, binary/multi-class decision, low-dimensional control law.
+* No general-purpose LM or large feature spaces.
+* Input/output dimensions very small (typically ≤ 8–16).
+
+## 2. Numeric Representation
+
+* Word: 15-bit data (modern 16-bit with 1-bit reserved).
+* Fixed-point Qm.n (e.g., Q1.14, Q3.12, Q7.8) chosen per variable, scale documented per quantity.
+* Double/triple precision only where required.
+* Saturation handling: clamp, wrap, or flag — defined per variable.
+
+## 3. Memory Layout
+
+**Erasable (RAM) — ~2K words target:**
+State vector, input buffer, accumulators, flags/mode bits, tiny stack.
+
+**Fixed (ROM) — majority:**
+Model constants (weights/biases, lookup tables, scale factors), code/macros, pre-computed coefficients. Bank/segment switching optional.
+
+## 4. Core Data Structures
+
+```
+STATE  : fixed-point vector (persistent)
+INPUT  : fixed-point vector (current observation)
+OUTPUT : fixed-point vector or discrete command
+ACC    : accumulator(s) — single/double precision
+SCALES : constant scale factors
+FLAGS  : mode, validity, saturation bits
+```
+
+## 5. Macro Routine Categories
+
+`LOAD_INPUT` / `SCALE_INPUT` · `MATVEC_TINY` / `DOT_PRODUCT_FIXED` (unrolled) · `LOOKUP_SEGMENT` / `PIECEWISE_LINEAR` · `ACTIVATE` (clip/ReLU/threshold) · `UPDATE_STATE` · `NORMALIZE`/`RESCALE` · `SATURATE` · `EMIT_OUTPUT`
+
+Macros expand to shifts, adds, MUL16, and table lookups — no floating point.
+
+## 6. Forward Pass
+
+```
+1. Acquire and scale input → INPUT
+2. Optional tiny feature transform
+3. Core block(s) (mat-vec + nonlinearity, macro-expanded)
+4. State update (if recurrent)
+5. Output scaling + saturation
+6. Write command / flags
+```
+
+All steps use fixed-point ops and explicit erasable temporaries.
+
+## 7. Initialization
+
+Weights/biases/tables in fixed storage; init routine copies needed values to erasable once. Constants never modified at runtime.
+
+## 8. Executive Wrapper (Optional)
+
+Cyclic/priority executive, ability to skip non-critical sections under pressure, watchdog/validity flags.
+
+## 9. Documentation Requirement
+
+For every variable and macro: Qm.n format, physical units, scale, valid range, overflow behavior, memory location (erasable bank or fixed address).
+
+## 10. Example Skeleton
+
+```
+; FIXED (ROM)
+WEIGHTS_Q3_12 ...
+BIAS_Q3_12 ...
+SCALE_IN ...  SCALE_OUT ...
+
+; ERASABLE (RAM)
+STATE DS 4 ; Q3.12
+INPUT DS 4
+OUTPUT DS 2
+ACC DS 2 ; double precision
+
+; MACROS
+MACRO DOT4 ; 4-element dot
+MACRO SAT_Q3_12
+MACRO UPDATE_STATE
+
+INFER
+    LOAD_INPUT
+    SCALE_INPUT
+    DOT4 WEIGHTS_Q3_12, INPUT, ACC
+    ADD BIAS
+    SAT_Q3_12
+    UPDATE_STATE
+    SCALE_OUTPUT
+    STORE OUTPUT
+    RETURN
+```
+
+## Design Principles
+
+Every bit budgeted — tables + interpolation over general arithmetic — unrolled tiny loops — minimal contiguous mutable state — specialized routine, not general engine.
+
+---
+
+## Fixed-Point Contract (INFER4 Example)
+
+4-input binary decision, Q format per quantity, saturate to 32-bit ACC.
+
+| Symbol | Format | Role | Overflow |
+|---|---|---|---|
+| `INPUT[4]` | Q1.14 | sensors [-1,1) | clamp |
+| `WEIGHTS[4]` | Q1.14 | ROM coefficients | const |
+| `BIAS` | Q3.12 | offset | const |
+| `ACC` | Q7.24 32-bit | dot accumulator | saturate |
+| `STATE` | Q3.12 | smoothed output | clamp |
+| `OUTPUT` | Q1.14 | command | clamp |
+| `FLAGS` | bits | validity/sat/decision | — |
+
+Q1.14 * Q1.14 → Q2.28 → >>4 → Q3.24 (4 products in 32-bit), >>12 → Q3.12 + `BIAS`.
+
+## Memory Map
+
+```
+; FIXED / ROM
+WEIGHTS_Q1_14: DC 2458, -1638, 819, 3277
+BIAS_Q3_12: DC -256
+ALPHA_Q1_14: DC 12288 ; 0.75
+ONE_Q1_14: DC 16384
+OUT_MIN_Q1_14: DC -16384
+OUT_MAX_Q1_14: DC 16383
+SCORE_MIN_Q3_12: DC -8192 ; -2.0 Q3.12
+SCORE_MAX_Q3_12: DC 8191  ; +2.0
+
+; ERASABLE / RAM
+INPUT: DS 4
+STATE: DS 1 ; Q3.12
+OUTPUT: DS 1
+ACC_HI: DS 1 ; 32-bit hi
+ACC_LO: DS 1 ; 32-bit lo
+TMP0: DS 1
+TMP1: DS 1
+FLAGS: DS 1
+FLAG_VALID=0001  FLAG_SAT=0002  FLAG_POSITIVE=0004
+```
+
+## Primitive Macros
+
+See `examples/infer4.asm` for full `CLR_ACC`, `MAC_Q1_14` (preserves `PROD_HI:PROD_LO` before `ADD32`), `ACC_TO_Q3_12`, `SAT_Q3_12`, `DOT4_Q1_14`, `THRESHOLD_Q3_12` (+1.0/-1.0), `UPDATE_STATE_3_4` (`(3*STATE+TARGET)/4`).
+
+## INFER4 Routine
+
+`examples/infer4.asm` — `INFER4: CLR FLAGS → DOT4 → ACC_TO_Q3_12 → ADD BIAS → SAT → THRESHOLD → UPDATE_STATE_3_4 → OUTPUT=STATE → FLAG_VALID → RET`
+
+Simulator: `python src/sim.py` (Q1.14/Q3.12 fixed-point, matches assembly semantics).
+
+## References
+
+[1] Virtual AGC Manual — ibiblio.org/apollo/assembly_language_manual.html
+[2] AGC — Wikipedia
+[3] Block II: 2048 erasable + 36864 fixed words, 15 data bits + parity
+
+---
+
+## License
+
+Licensed under **SnapKitty Tri-License**. Full text: [LICENSE.tri](LICENSE.tri).
+
+### 💼 Commercial License
+
+Snapkitty code is free and open under **AGPL-3.0** for open-source use. Building a commercial product or service? A **proprietary commercial license** from Snapkitty Collective LLC lets you ship this code without the AGPL's source-sharing and network-use obligations.
+
+**[→ Get a commercial license](mailto:A.parr@belespritdaccord.uk?subject=Commercial%20license:%20MACROGROK)** · A.parr@belespritdaccord.uk