Release: v0.4 — Architectural Baseline

[Kyonax]

Checklist (check if it applies)

• Contains testing instructions
• Requires environment / credential changes
• Requires special deployment steps
• Has unit / integration tests
• Touches licensing, security, or CI
• License headers on new files (LICENSING.org)
• Attribution preserved on modified files
• Lint passes (npm run lint)
• Security rules followed (SECURITY.org)
• No credentials committed
• All GitHub Checks have passed (no Pre-Check Failed label applied by CI)
• CHANGELOG.org updated (release PRs only)
• Version bumped (release PRs only)

Release triad is still pending — the last two checklist items will flip to [x] once the [v0.4] block lands in CHANGELOG.org, the #+VERSION: markers in README.org move from v0.3 to v0.4, and package.json bumps to 0.4.0. See Special Deployment Requirements below for the exact commands.

What does this PR do?

Ships RECKIT v0.4 to master. Fast-forwards the default branch with the architectural refactor already reviewed and merged into dev via PR #3. Contents are five commits (three feature + fix commits from the earlier feat-fixes-and-refinement-v3 cycle, one Session 7 Part B commit, and the merge commit from PR #3) — no further code changes since that merge.

This release promotes the kind-folder component architecture, 11-alias Vite registry, three new shared/components/ui/ primitives, brand folder restructure into sources/, and the SCSS-single-source-of-truth brand theming chain to master. v0.4 becomes the architectural baseline on which all subsequent brand work builds — starting with the already-branched feat-brand_kot for @kyonax_on_tech expansion.

As the repo maintainer, I want an explicit dev to master release PR that gates on the release.yml CHANGELOG + version workflow, so that every release on master has a matching git tag, a GitHub Release entry, and the architectural baseline captured with its version number.

Design / Reference: Release notes in CHANGELOG.org under the [v0.4] entry (to be added as part of this PR). Architecture rules codified in CONTRIBUTING.org. Full feature-level narrative in the merged PR #3.

Implementation

[NEW] new file · [MOD] modified file · [DEL] removed · [MOV] renamed or relocated

This is a release merge PR. The file inventory is already captured in the merged feature PR. Each bullet below summarizes a theme from the v0.3 to v0.4 delta and cross-references PR #3 for the complete file list, prop shapes, and migration notes. Lines below intentionally do not repeat the full per-file inventory.

• Brand-driven architecture — each @brand/ folder is the single source of truth; brand-loader.js auto-discovers via import.meta.glob; dynamic routing from discovered sources; centralized overlays.js deleted in favor of per-brand sources.js. (see PR #3 for detail)
• Kind-folder component architecture — views/components/ split into sections/ + elements/ + modals/; shared/components/ split into ui/ + hud/; shared/widgets/ split into widgets/hud/ + widgets/ui/; five sections extracted from home.vue (~655 lines down to ~80); brand folders restructured so web sources live under <brand>/sources/<type>/<id>.vue. (see PR #3 for detail)
• Three new shared/components/ui/ primitives — <UiDataPoint> (label/value tile), <UiChip> (lowercase pill), <UiBadge> (uppercase status pill); ~40 lines of duplicated SCSS removed across stats.vue / card.vue / detail.vue consumers. (see PR #3 for detail)
• Eleven Vite aliases — four top-level scopes (@shared, @views, @app, @assets) + seven kind-folder aliases (@sections, @elements, @modals, @ui, @hud, @widgets, @composables). (see PR #3 for detail)
• Brand theming — SCSS single source of truth — @<brand>/styles/_theme.scss auto-loaded at build by an eager glob in src/main.js; brand.js no longer carries a colors field (enforced by brand-loader.test.js); App.vue applies the .brand-<handle> class and the CSS cascade resolves every var(--clr-*) call. (see PR #3 for detail)
• <UiIcon> multi-pool SVG discovery — scans both @shared/assets/svg/*.svg and /@*/assets/svg/*.svg; brand SVGs override shared on filename collision. (see PR #3 for detail)
• Utils as topic-based libraries (Rule J) — views/utils/parse-emphasis.js renamed to views/utils/markup.js; parseEmphasis stays a named export; future inline-markup parsers absorb into the same file. (see PR #3 for detail)
• ESLint Vue SFC + @typescript-eslint/naming-convention — CCS naming rules machine-enforced across .js and .vue; tsconfig.eslint.json wires the TS parser for allowJs. (see PR #3 for detail)
• Tier 1 file headers — figlet smslant ASCII art + cyberpunk place names applied to 15 root config / setup / org files (the gate, the forge, the precinct, the void, the lab, the vault, the watchtower, the checkpoint, the logs, the bridge, the pact, the law, the dojo, the shield, the scroll). (see PR #3 for detail)
• Overlay card fixes + <DetailModal> — mobile-first 1fr grid, 3-line description clamp, max 3 use-case chips with +N overflow, always-visible DETAILS button wired to a full-source-info modal. (see PR #3 for detail)
• CONTRIBUTING.org + expanded SECURITY.org — setup / conventions / CI / PR process (the dojo); banned-pattern tables, enforcement layers, contributor checklist (the shield). (see PR #3 for detail)

Release

Version: v0.4 (was v0.3)

• [MOD] package.json — version bumped from 0.3.0 to 0.4.0 (PENDING — run npm version 0.4.0 --no-git-tag-version on dev before merge)
• [MOD] README.org — #+VERSION: v0.3 to v0.4, ASCII logo footer ░v0.3 to ░v0.4, shields.io badge version-v0.3 to version-v0.4, alt="v0.3" to alt="v0.4", #+LAST_UPDATE: refreshed to today (PENDING)
• [MOD] CHANGELOG.org — new [v0.4] — 2026-04-21 :: Architectural Baseline block added above [v0.3] with Added / Changed / Removed / Decided subsections (PENDING)

The release.yml workflow gates the dev to master PR on the three-file triad above. CI will remain red until all three land.

CI & Tooling

• No CI or tooling changes in v0.4 beyond what PR #3 already shipped to dev (vite.config.js with 11 aliases, eslint.config.mjs with Vue SFC support, tsconfig.eslint.json).

Dependencies

• Runtime added: —
• Dev added: — (nothing new beyond PR #3 — eslint-plugin-vue, vue-eslint-parser, @typescript-eslint/parser, @typescript-eslint/eslint-plugin are already on dev from that PR)
• Upgraded: —
• Removed: —
• Lockfile: no change since PR #3

Docs

• [MOD] CHANGELOG.org — [v0.4] entry to be added (see Release subsection above); serves as the primary release notes artifact for gh release create.
• Architecture documentation (CONTRIBUTING.org, SECURITY.org, README.org) was last updated by PR #3 — no further doc edits in this release PR.

Technical Details

• Release-cut strategy — ship Sessions 6 + 7 A+B as v0.4, hold feat-brand_kot for a later tag

  • Chose: Cut v0.4 from the current dev state, which captures the merged feat-fixes-and-refinement-v3 branch (kind-folder architecture + naming convention + SCSS theming fix) as a coherent architectural baseline.
  • Over: Waiting for the in-flight feat-brand_kot branch (Session 8, @kyonax_on_tech brand expansion including the planned item-explain.vue animation web source) to merge into dev first and shipping a combined v0.4.
  • Why: Sessions 6 + 7 A+B form a self-contained refactor that is already merged, validated, and stable. Tagging it on master now gives downstream brand work (starting with feat-brand_kot) a named baseline to build against. Delaying would couple two independent efforts into one tag and increase rollback blast radius if either needs to be reverted.
  • Trade-off: feat-brand_kot will land in v0.4.1 or v0.5 instead of v0.4. Observers watching only master tags will see two smaller releases rather than one combined release.

• Release artifact flow — release.yml enforces the version triad on every dev to master PR

  • Chose: Rely on the existing release.yml gate that requires package.json version, README.org #+VERSION: markers, and a new CHANGELOG.org [vX.Y] block to land on dev before this PR can pass CI.
  • Over: Manual version-sync scripts run by the maintainer, or a release-bot automation outside of CI.
  • Why: CI-enforced gating prevents partial version bumps (e.g. package.json updated but README forgotten) from reaching master. The triad is the single contract every release PR must satisfy; release.yml is the load-bearing check.
  • Trade-off: The triad must be completed on dev before this PR turns green — an extra pre-merge step versus a single-file bump. The benefit is that master never carries a mismatched version string between package.json and the visible UI / badges.

• Architectural baseline semantics — v0.3 stays the "CAM-LOG first release", v0.4 becomes the "architecture baseline"

  • Chose: Publish v0.4 as the tag that captures the kind-folder split, 11-alias registry, and SCSS-single-source-of-truth brand theming as the foundation for all subsequent v0.4.x and v0.5 brand / widget work.
  • Over: Staying on v0.3 and treating Sessions 6 + 7 as untagged internal refinement.
  • Why: The feat-brand_kot branch (and every future brand expansion) relies on the new folder conventions, aliases, and theming rules. Having a named tag for that foundation makes git bisection and rollback trivial if a later brand-specific change regresses the architecture; it also gives the CHANGELOG a natural point to describe the architecture rather than mixing it into a feature entry.
  • Trade-off: Two "meaningful" tags close together on the timeline (v0.3 for the first working CAM-LOG overlay + landing page, v0.4 a week later for the refactor). The release cadence is acceptable for a solo project; downstream consumers don't exist yet.

Testing Coverage

Test runner: Vitest @ 4.1.x
Command: npm run test

Automated tests

Full per-file breakdown is in the PR #3 Testing Coverage section. Summary for this release:

Total: 27 tests across 2 files (src/shared/brand-loader.test.js, src/shared/version.test.js), all passing.

Quality gates (run on every PR)

Gate	Source	Status
Lint	eslint.config.mjs via npm run lint	✅ 0 errors (7 known warnings in use-audio-analyzer.js array indexing)
Unit tests	vite.config.js via npm run test	✅ 27 passing
Build	vite.config.js via npm run build	✅ clean, 1.25s
Security scan	.github/workflows/ci.yml	✅
License headers	.github/workflows/ci.yml	✅
Pre-Check Failed label	pre-check-label job in .github/workflows/ci.yml	✅ label absent
Release triad	.github/workflows/release.yml	⚠️ pending until triad lands on dev

How to test this PR

Release v0.4 verification
├─ Pre-merge — triad readiness
├─ Post-merge — master baseline pipeline
├─ Post-merge — UI version surfaces
└─ Post-tag — GitHub Release artifact

Pre-merge — triad readiness

Prereqs: checked out on dev locally, pulled to HEAD

1. grep '"version"' package.json
   Expected: prints "version": "0.4.0", — the bump from 0.3.0 has already landed on dev
2. grep -nE '#\+VERSION:|░v[0-9]|badge/version-v|alt="v[0-9]|#\+LAST_UPDATE' README.org | head -10
   Expected: every matching line reads v0.4; #+LAST_UPDATE: reads today's date
3. grep -n '^\*\s\+\[v' CHANGELOG.org | head -5
   Expected: first match is [v0.4] — 2026-04-21 :: <Short Title>; second match is [v0.3]
4. npm run lint && npm run test && npm run build
   Expected: all three commands exit 0; build finishes under 2 seconds; dist/assets/ contains the hashed index-*.css, index-*.js, home-*.js, cam-log-*.js, version-*.js bundles
5. gh pr checks 4 --watch
   Expected: all gates turn green; release.yml no longer blocks

Post-merge — master baseline pipeline

Prereqs: PR #4 merged to master

1. Fresh clone into a scratch directory — git clone https://github.com/Kyonax/reckit.git /tmp/reckit-v0.4 && cd /tmp/reckit-v0.4
   Expected: clones successfully; git log --oneline -5 shows the merge commit from this PR at the top of master
2. npm ci && npm run lint && npm run test && npm run build
   Expected: clean install, zero lint errors, 27/27 tests pass, build exits 0 under 2 seconds
3. cat package.json | grep version
   Expected: "version": "0.4.0"

Post-merge — UI version surfaces

Prereqs: master clone, dev server running via npm run dev on http://localhost:5173/

1. Open http://localhost:5173/ and look at the top sticky stats bar + the top-right SYS.LOG tag
   Expected: the right-side tag reads RECKIT v0.4 (derived from package.json via __APP_VERSION__ in vite.config.js and src/shared/version.js)
2. Navigate to http://localhost:5173/@kyonax_on_tech/cam-log
   Expected: the HUD overlay renders; the toolkit-id label in the bottom-right reads RECKIT v0.4
3. Inspect the README page on GitHub after merge
   Expected: ASCII logo footer shows ░v0.4; shields.io badge shows version v0.4

Post-tag — GitHub Release artifact

Prereqs: v0.4 tag pushed to origin

1. Navigate to https://github.com/Kyonax/reckit/releases/tag/v0.4
   Expected: release page renders; title reads RECKIT v0.4; body contains the [v0.4] slice from CHANGELOG.org
2. Download / inspect the auto-generated source tarball
   Expected: tarball matches the master tree at the tag commit

Special Deployment Requirements

1. Version bump in package.json (CRITICAL) — run npm version 0.4.0 --no-git-tag-version on dev before merge. Stages the bump without creating a tag (the tag is applied post-merge on master).
2. README version markers bumped to v0.4 (CRITICAL) — run the four sed -i -E patches from the release runbook to update #+VERSION:, ASCII logo footer, shields.io badge, alt="v0.3", and #+LAST_UPDATE: on dev.
3. CHANGELOG.org gets a [v0.4] block (CRITICAL) — insert above [v0.3] with Added / Changed / Removed / Decided subsections; reference PR #3 for the full per-file inventory; summarize the theme delta (kind-folder architecture, 11 aliases, 3 new ui primitives, SCSS theming fix, brand restructure).
4. Tag v0.4 on master (REQUIRED, post-merge) — git tag -a v0.4 -m "RECKIT v0.4" then git push origin v0.4. Enables the GitHub Release step and marks the architecture baseline.
5. GitHub Release with CHANGELOG notes (OPTIONAL, post-tag) — extract the [v0.4] slice from CHANGELOG.org into a temp file, then gh release create v0.4 --title "RECKIT v0.4" --notes-file <file>. Produces a browsable release page and attaches source tarballs.
6. Branch protection on master (OPTIONAL, one-time) — enable "Require a pull request before merging" + "Require status checks to pass" (include release.yml, ci.yml, pre-check-label) in repo settings. Prevents direct pushes to master and enforces the triad contract going forward.

Documentation

DIAGRAM — v0.3 to v0.4 delta

Architectural baseline tag. Kind-folder component split + 11 Vite aliases + SCSS-single-source-of-truth brand theming become the foundation for all subsequent brand work.

Full narrative in the merged PR #3. Canonical architecture rules in CONTRIBUTING.org (Rules A–J covering component classification, extraction discipline, folder existence, aliases, import bindings, and topic-library utils).

DESKTOP — Landing page at v0.4

Sticky stats bar, WEB SOURCES grid, kind-split view components (<StatsSection>, <HeroSection>, <SetupSection>, <SourcesSection>, <FooterSection>), new ui primitives (<UiDataPoint>, <UiChip>, <UiBadge>).

Demo capture pending, will be attached after tag + release.

DIAGRAM — Brand theming SCSS single source of truth

Three-layer flow: src/app/scss/abstracts/_theme.scss declares :root defaults; @<brand>/styles/_theme.scss redeclares any subset inside .brand-<handle>, auto-loaded by src/main.js's eager glob; src/App.vue applies the brand class on route change and the CSS cascade resolves every var(--clr-*) to the brand override or the :root default.

Full flow in CONTRIBUTING.org under the brand-theming architecture section.

[github-actions]

Protected Files Modified

One or more files in the protected set were changed in this PR. Each category below explains why the file matters.

Legal / Licensing

• LICENSING.org was modified

Modifying these files changes the project's legal posture. Confirm with the maintainer before merging.

Governance

• .github/SECURITY.org was modified
• .github/PULL_REQUEST_TEMPLATE.md was modified

CODEOWNERS / SECURITY / PR template changes affect how every future PR is reviewed. Review carefully.

Supply Chain

• package.json was modified
• package-lock.json was modified

Dependency or lockfile changes. Verify the diff (no unexpected packages, no version downgrades).

CI / Security Config

• .github/workflows/ci.yml was modified
• .github/workflows/release.yml was modified
• eslint.config.mjs was modified

Workflow / lint config. A quiet edit here can disable gates — diff against origin carefully.

Build / Config

• vite.config.js was modified
• .gitignore was modified
• .env.example was modified

Build or gitignore config. Verify the build still passes and no ignored paths were accidentally un-ignored.

Release Artifact

• CHANGELOG.org was modified
• README.org was modified

Release-tracking files. Expected on release PRs; flag on non-release PRs.