scriber-core 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. scriber_core-1.0.0/.devcontainer/devcontainer.json +20 -0
  2. scriber_core-1.0.0/.github/workflows/publish.yml +164 -0
  3. scriber_core-1.0.0/.gitignore +49 -0
  4. scriber_core-1.0.0/.junie/AGENTS.md +89 -0
  5. scriber_core-1.0.0/.junie/skills/cosmic-visual-styling/SKILL.md +213 -0
  6. scriber_core-1.0.0/CHANGELOG.md +58 -0
  7. scriber_core-1.0.0/LICENSE +21 -0
  8. scriber_core-1.0.0/PKG-INFO +256 -0
  9. scriber_core-1.0.0/README.md +213 -0
  10. scriber_core-1.0.0/TODO.md +73 -0
  11. scriber_core-1.0.0/boilerplates/__init__.py +8 -0
  12. scriber_core-1.0.0/boilerplates/css/tse-boilerplate.css +235 -0
  13. scriber_core-1.0.0/boilerplates/mermaid/boilerplate_diagram.mmd +85 -0
  14. scriber_core-1.0.0/boilerplates/notebooks/visuals-boilerplate.ipynb +871 -0
  15. scriber_core-1.0.0/boilerplates/python/__init__.py +95 -0
  16. scriber_core-1.0.0/boilerplates/python/gold-standard.py +483 -0
  17. scriber_core-1.0.0/boilerplates/python/visualization_boilerplate.py +119 -0
  18. scriber_core-1.0.0/docs/COOP_blog/Packaging/302/240guide /302/267 The COOP Blog.html" +286 -0
  19. scriber_core-1.0.0/docs/COOP_blog/Python packages_ the COOP gold/302/240standard /302/267 The COOP Blog.html" +601 -0
  20. scriber_core-1.0.0/docs/COOP_blog/The COOP Click Command line/302/240interfaces /302/267 The COOP Blog.html" +408 -0
  21. scriber_core-1.0.0/docs/COOP_blog/The Coop Cactus branching/302/240model /302/267 The COOP Blog.html" +307 -0
  22. scriber_core-1.0.0/docs/COOP_blog/Using the json-SCHEMA standard for scientific/302/240applications_ /302/267 The COOP Blog.html" +604 -0
  23. scriber_core-1.0.0/docs/PYPI_UPLOAD.md +74 -0
  24. scriber_core-1.0.0/docs/colors-and-gradients.md +146 -0
  25. scriber_core-1.0.0/docs/workspace-setup-guide.md +678 -0
  26. scriber_core-1.0.0/house-rules/css-rules.md +117 -0
  27. scriber_core-1.0.0/house-rules/python-rules.md +402 -0
  28. scriber_core-1.0.0/pyproject.toml +83 -0
  29. scriber_core-1.0.0/src/scriber_core/__init__.py +28 -0
  30. scriber_core-1.0.0/src/scriber_core/cli/__init__.py +164 -0
  31. scriber_core-1.0.0/src/scriber_core/cli/__main__.py +17 -0
  32. scriber_core-1.0.0/src/scriber_core/cli/branding.py +314 -0
  33. scriber_core-1.0.0/src/scriber_core/cli/colors_table.py +721 -0
  34. scriber_core-1.0.0/src/scriber_core/cli/command_catalog.py +339 -0
  35. scriber_core-1.0.0/src/scriber_core/cli/main.py +713 -0
  36. scriber_core-1.0.0/src/scriber_core/cli/messaging.py +742 -0
  37. scriber_core-1.0.0/src/scriber_core/cli/smoke_tests.py +168 -0
  38. scriber_core-1.0.0/src/scriber_core/cli/vt_mode.py +114 -0
  39. scriber_core-1.0.0/src/scriber_core/frontend/__init__.py +98 -0
  40. scriber_core-1.0.0/src/scriber_core/frontend/colors.py +575 -0
  41. scriber_core-1.0.0/src/scriber_core/frontend/gradients.py +365 -0
  42. scriber_core-1.0.0/src/scriber_core/frontend/the_scriber_experience/__init__.py +76 -0
  43. scriber_core-1.0.0/src/scriber_core/frontend/the_scriber_experience/mermaid/__init__.py +31 -0
  44. scriber_core-1.0.0/src/scriber_core/frontend/the_scriber_experience/mermaid/theme.py +543 -0
  45. scriber_core-1.0.0/src/scriber_core/frontend/the_scriber_experience/plots/__init__.py +160 -0
  46. scriber_core-1.0.0/src/scriber_core/frontend/the_scriber_experience/plots/theme.py +1160 -0
  47. scriber_core-1.0.0/sublime-theme/EigenScribe/color-schemes/EigenScribe.sublime-color-scheme +213 -0
  48. scriber_core-1.0.0/sublime-theme/EigenScribe/snippets/ptx-definition.sublime-snippet +11 -0
  49. scriber_core-1.0.0/sublime-theme/EigenScribe/snippets/ptx-math-display.sublime-snippet +8 -0
  50. scriber_core-1.0.0/sublime-theme/EigenScribe/snippets/ptx-math-inline.sublime-snippet +6 -0
  51. scriber_core-1.0.0/sublime-theme/EigenScribe/snippets/ptx-proof.sublime-snippet +11 -0
  52. scriber_core-1.0.0/sublime-theme/EigenScribe/snippets/ptx-section.sublime-snippet +12 -0
  53. scriber_core-1.0.0/sublime-theme/EigenScribe/snippets/ptx-theorem.sublime-snippet +11 -0
  54. scriber_core-1.0.0/sublime-theme/EigenScribe/snippets/ptx-xref.sublime-snippet +6 -0
  55. scriber_core-1.0.0/sublime-theme/EigenScribe/sublime-package.json +26 -0
  56. scriber_core-1.0.0/sublime-theme/EigenScribe/syntaxes/PreTeXt.sublime-syntax +148 -0
  57. scriber_core-1.0.0/sublime-theme/EigenScribe/themes/EigenScribe.sublime-theme +387 -0
  58. scriber_core-1.0.0/sublime-theme/README.md +291 -0
  59. scriber_core-1.0.0/sublime-theme/install.ps1 +70 -0
  60. scriber_core-1.0.0/sublime-theme/install.sh +90 -0
  61. scriber_core-1.0.0/tests/conftest.py +4 -0
  62. scriber_core-1.0.0/tests/func/__init__.py +1 -0
  63. scriber_core-1.0.0/tests/unit/test_cli.py +205 -0
  64. scriber_core-1.0.0/tests/unit/test_cli_colors_table.py +284 -0
  65. scriber_core-1.0.0/tests/unit/test_cli_messaging.py +388 -0
  66. scriber_core-1.0.0/tests/unit/test_frontend_styling.py +120 -0
  67. scriber_core-1.0.0/uv.lock +3325 -0
@@ -0,0 +1,20 @@
1
+ {
2
+ "name": "Scriber Core",
3
+ "image": "://microsoft.com",
4
+
5
+ // Automatically install 'uv' and set up a virtual environment upon creation
6
+ "postCreateCommand": "curl -LsSf https://astral.sh | sh && uv venv",
7
+
8
+ "customizations": {
9
+ "vscode": {
10
+ "settings": {
11
+ "python.defaultInterpreterPath": ".venv/bin/python",
12
+ "python.experimental.features": true
13
+ },
14
+ "extensions": [
15
+ "ms-python.python",
16
+ "ms-python.vscode-pylance"
17
+ ]
18
+ }
19
+ }
20
+ }
@@ -0,0 +1,164 @@
1
+ # ---------------------------------------------------------------------------------------------------------
2
+ # 🚀 Publish scriber-core to PyPI (Trusted Publishing / OIDC)
3
+ # ---------------------------------------------------------------------------------------------------------
4
+ #
5
+ # This workflow builds the `scriber-core` distributions with `uv build` and uploads them with
6
+ # `uv publish`, following the COOP "Distribution & PyPI Publishing Protocol" documented in
7
+ # docs/workspace-setup-guide.md (Section 11) and the official uv / PyPA GitHub Actions guides.
8
+ #
9
+ # It uses **Trusted Publishing (OIDC)** — no API tokens or secrets are stored in the repo.
10
+ #
11
+ # ── One-time setup (required before the first release) ───────────────────────────────────────────────
12
+ # 1. Create the project on PyPI (name: `scriber-core`). For the very first upload you may need to
13
+ # use the "pending publisher" flow: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/
14
+ # 2. On PyPI → your project → Settings → Publishing → "Add a new pending/trusted publisher":
15
+ # • Owner: The-Scriber-Experience
16
+ # • Repository name: scriber-core
17
+ # • Workflow name: publish.yml
18
+ # • Environment name: pypi
19
+ # (Repeat on https://test.pypi.org with Environment name `testpypi` if you want TestPyPI runs.)
20
+ # 3. (Recommended) In GitHub → Settings → Environments, create environments named `pypi` and
21
+ # `testpypi`. You can add required reviewers to `pypi` to gate production releases behind a
22
+ # manual approval.
23
+ #
24
+ # ── How to release ──────────────────────────────────────────────────────────────────────────────────
25
+ # • Production: bump the version in pyproject.toml + src/scriber_core/__init__.py, update CHANGELOG.md, then push
26
+ # an annotated tag, e.g. `git tag -a v1.0.1 -m "Release 1.0.1" && git push origin main --tags`.
27
+ # The tag push runs tests → builds → publishes to PyPI automatically.
28
+ # • Dry run / TestPyPI: use the "Run workflow" button (workflow_dispatch) and pick a target.
29
+ #
30
+ # ── Prefer API tokens instead of OIDC? ────────────────────────────────────────────────────────────────
31
+ # Remove the `permissions: id-token: write` + `environment:` blocks from the publish jobs, add a
32
+ # `PYPI_API_TOKEN` repository secret, and change the publish step to:
33
+ # run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}
34
+ # ---------------------------------------------------------------------------------------------------------
35
+
36
+ name: Publish to PyPI
37
+
38
+ on:
39
+ push:
40
+ tags:
41
+ # Publish on SemVer version tags, e.g. v1.0.0, v1.2.3rc1, v2.0.0a1, v2.0.0b2
42
+ - "v[0-9]+.[0-9]+.[0-9]+"
43
+ - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
44
+ - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"
45
+ workflow_dispatch:
46
+ inputs:
47
+ publish_target:
48
+ description: "Manual run target (tag pushes always go to PyPI)"
49
+ type: choice
50
+ default: testpypi
51
+ options:
52
+ - testpypi
53
+ - pypi
54
+
55
+ # Least-privilege default for every job; the publishing jobs opt into `id-token: write` explicitly.
56
+ permissions:
57
+ contents: read
58
+
59
+ jobs:
60
+ # -------------------------------------------------------------------------------------------------------
61
+ # 1️⃣ Test across every supported Python version before anything is built or published.
62
+ # -------------------------------------------------------------------------------------------------------
63
+ test:
64
+ name: Test (Python ${{ matrix.python-version }})
65
+ runs-on: ubuntu-latest
66
+ strategy:
67
+ fail-fast: false
68
+ matrix:
69
+ python-version: ["3.10", "3.11", "3.12"]
70
+ steps:
71
+ - name: Checkout repository
72
+ uses: actions/checkout@v4
73
+
74
+ - name: Install uv (Python ${{ matrix.python-version }})
75
+ uses: astral-sh/setup-uv@v6
76
+ with:
77
+ python-version: ${{ matrix.python-version }}
78
+ enable-cache: true
79
+
80
+ - name: Run the test suite
81
+ run: uv run --extra dev pytest tests
82
+
83
+ # -------------------------------------------------------------------------------------------------------
84
+ # 2️⃣ Build the sdist + wheel once, smoke-test the wheel, and hand the artifacts to the publish jobs.
85
+ # This job intentionally has NO id-token permission (reduces supply-chain attack surface).
86
+ # -------------------------------------------------------------------------------------------------------
87
+ build:
88
+ name: Build distributions
89
+ needs: test
90
+ runs-on: ubuntu-latest
91
+ steps:
92
+ - name: Checkout repository
93
+ uses: actions/checkout@v4
94
+
95
+ - name: Install uv
96
+ uses: astral-sh/setup-uv@v6
97
+
98
+ - name: Build sdist and wheel
99
+ run: uv build
100
+
101
+ - name: Smoke-test the built wheel
102
+ run: >-
103
+ uv run --isolated --no-project --with dist/*.whl
104
+ python -c "import importlib.metadata as m; import scriber_core; from scriber_core import frontend, cli;
105
+ print('scriber-core', m.version('scriber-core'), '| scriber_core', scriber_core.__version__, '| frontend', frontend.__version__)"
106
+
107
+ - name: Upload distribution artifacts
108
+ uses: actions/upload-artifact@v4
109
+ with:
110
+ name: dist
111
+ path: dist/
112
+ if-no-files-found: error
113
+
114
+ # -------------------------------------------------------------------------------------------------------
115
+ # 3️⃣ Publish to PyPI — on version-tag pushes, or a manual run with target = pypi.
116
+ # -------------------------------------------------------------------------------------------------------
117
+ publish-pypi:
118
+ name: Publish to PyPI
119
+ needs: build
120
+ if: github.event_name == 'push' || github.event.inputs.publish_target == 'pypi'
121
+ runs-on: ubuntu-latest
122
+ environment:
123
+ name: pypi
124
+ url: https://pypi.org/project/scriber-core/
125
+ permissions:
126
+ id-token: write # Mandatory for Trusted Publishing (OIDC)
127
+ steps:
128
+ - name: Download distribution artifacts
129
+ uses: actions/download-artifact@v4
130
+ with:
131
+ name: dist
132
+ path: dist/
133
+
134
+ - name: Install uv
135
+ uses: astral-sh/setup-uv@v6
136
+
137
+ - name: Publish to PyPI
138
+ run: uv publish --trusted-publishing always
139
+
140
+ # -------------------------------------------------------------------------------------------------------
141
+ # 4️⃣ Publish to TestPyPI — manual runs only (the default workflow_dispatch target).
142
+ # -------------------------------------------------------------------------------------------------------
143
+ publish-testpypi:
144
+ name: Publish to TestPyPI
145
+ needs: build
146
+ if: github.event_name == 'workflow_dispatch' && github.event.inputs.publish_target == 'testpypi'
147
+ runs-on: ubuntu-latest
148
+ environment:
149
+ name: testpypi
150
+ url: https://test.pypi.org/project/scriber-core/
151
+ permissions:
152
+ id-token: write # Mandatory for Trusted Publishing (OIDC)
153
+ steps:
154
+ - name: Download distribution artifacts
155
+ uses: actions/download-artifact@v4
156
+ with:
157
+ name: dist
158
+ path: dist/
159
+
160
+ - name: Install uv
161
+ uses: astral-sh/setup-uv@v6
162
+
163
+ - name: Publish to TestPyPI
164
+ run: uv publish --trusted-publishing always --publish-url https://test.pypi.org/legacy/
@@ -0,0 +1,49 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.bak
6
+
7
+ # Distribution / packaging
8
+ build/
9
+ develop-eggs/
10
+ dist/
11
+ downloads/
12
+ eggs/
13
+ .eggs/
14
+ lib/
15
+ lib64/
16
+ parts/
17
+ sdist/
18
+ var/
19
+ wheels/
20
+ share/python-wheels/
21
+ *.egg-info/
22
+ .installed.cfg
23
+ *.egg
24
+
25
+ # Virtual environments
26
+ .venv/
27
+ venv/
28
+ ENV/
29
+ env/
30
+
31
+ # IDE and editor artifacts
32
+ .idea/
33
+ .vscode/
34
+ *.swp
35
+ *.swo
36
+ *~
37
+
38
+ # Data files, simulation artifacts & plots
39
+ *.npz
40
+ *.npy
41
+ *.h5
42
+ *.hdf5
43
+ /plots/
44
+ !src/**/plots/
45
+ *.log
46
+ benchmark.log
47
+
48
+ # PyPI upload config (contains credentials)
49
+ .pypirc
@@ -0,0 +1,89 @@
1
+ # 🔬 Scriber Core — Repo-Specific Agent Overlay
2
+
3
+ > **Two-layer design:** This file supplements the universal Eigenscribe workspace guidelines (provided in the system prompt). It only contains repo-specific overrides, references, and constraints for `scriber-core`. For all general Python engineering, CSS design system, tooling, and COOP standards, consult the system prompt guidelines.
4
+
5
+ ---
6
+
7
+ ## 📌 Repository Identity
8
+
9
+ **Package:** `scriber-core` (v1.0.0)
10
+ **Purpose:** Canonical workspace baseline for Eigenscribe Inc. and Scriber Labs, providing deterministic CLI styling tools, TrueColor gradient engines, design tokens, visualization themes, and the Scriber Experience (TSE) subsystem. Distributed via Git submodules, template cloning, or installable Python packaging.
11
+
12
+ **Packages:** Two installable packages under `src/`:
13
+ - **`src/frontend`** — Color palette (`COLOR_PALETTE`), gradient engine (`GRADIENT_PRESETS`), TSE styling subsystems (semantic roles, plots, Mermaid themes).
14
+ - **`src/cli`** — CLI suite with TrueColor gradient banners, palette table renderer, semantic messaging, and command catalog.
15
+
16
+ **Key Files:**
17
+ | File | Purpose |
18
+ | :--- | :--- |
19
+ | [`README.md`](README.md) | Master onboarding index, CLI usage, color standards, and cross-project distribution guide. |
20
+ | [`CHANGELOG.md`](CHANGELOG.md) | Version history following Keep a Changelog 1.0.0. |
21
+ | [`TODO.md`](TODO.md) | Current task backlog, deferred work, and implementation roadmap. |
22
+ | [`pyproject.toml`](pyproject.toml) | PEP 621 metadata, `hatchling` build backend, `uv` tooling config, dependencies, and CLI entry points. |
23
+
24
+ ---
25
+
26
+ ## 📁 Workspace Reference Files
27
+
28
+ All paths are relative to the project root. Agents must consult these before any code generation.
29
+
30
+ | Directory | File | Purpose & Contents |
31
+ | :--- | :--- | :--- |
32
+ | `house-rules` | `house-rules/python-rules.md` | Core rules for Python development: mathematical typography, modern RNG, typing, package hygiene, docstrings, and script flow. |
33
+ | `house-rules` | `house-rules/css-rules.md` | The Scriber Experience design system: 4-layer token hierarchy, glassmorphism baseline, ADHD semantic color coding, and golden ratio spacing. |
34
+ | `docs` | `docs/workspace-setup-guide.md` | Canonical workspace distribution, packaging, Diátaxis Sphinx docs, testing, and PyPI release guide. |
35
+ | `docs/COOP_blog` | `docs/COOP_blog/Python packages_ the COOP gold standard · The COOP Blog.html` | Foundational CERFACS COOP software engineering standard on Python packaging, testing, and continuous integration. |
36
+ | `docs/COOP_blog` | `docs/COOP_blog/Packaging guide · The COOP Blog.html` | Step-by-step COOP packaging, sdist/wheel distribution, and PyPI release governance guide. |
37
+ | `docs/COOP_blog` | `docs/COOP_blog/The COOP Click Command line interfaces · The COOP Blog.html` | Click-based CLI design, thin-wrapper command architecture, context routing, and CliRunner testing. |
38
+ | `docs/COOP_blog` | `docs/COOP_blog/The Coop Cactus branching model · The COOP Blog.html` | Single-trunk Cactus branching model, release stabilization branches, hotfixes, and annotated tag governance. |
39
+ | `docs/COOP_blog` | `docs/COOP_blog/Using the json-SCHEMA standard for scientific applications_ · The COOP Blog.html` | JSON Schema validation, fail-fast boundary enforcement, and parameter self-documentation for scientific input decks. |
40
+ | `src/frontend` | `src/frontend/the_scriber_experience/style/gradient_presets.py` | ANSI TrueColor multi-stop linear RGB gradient engine and color-stop presets. |
41
+ | `src/frontend` | `src/frontend/colors.py` | ANSI 256-color terminal palette, semantic level messaging, and CLI styling helpers. |
42
+ | `boilerplates` | `boilerplates/python/gold-standard.py` | Gold standard reference script template implementing mathematical simulation, explicit type annotations, shape assertions, deterministic RNG, and smoke testing. |
43
+ | `src/frontend` | `src/frontend/the_scriber_experience/plots/theme.py` | Generalizable visualization bootstrapping script for Matplotlib, Pyplot, and Seaborn with high-contrast curves, deep cosmic void palettes, and 6-style heatmaps. |
44
+ | `boilerplates` | `boilerplates/css/tse-boilerplate.css` | Gold standard reference stylesheet implementing the full 4-layer taxonomy, CSS tokens, cosmic radial gradients, Sephirah labels, glassmorphism components, and responsive layouts. |
45
+ | `boilerplates` | `boilerplates/notebooks/visuals-boilerplate.ipynb` | Gold standard reference notebook template for scientific visualization, NetworkX graph topologies, dashboards, and design token / colormap palettes. |
46
+ | `.junie/skills` | `.junie/skills/cosmic-visual-styling/SKILL.md` | Workspace skill for applying the Sephirah / cosmic visual themes, color tokens, and glassmorphic UI components. |
47
+
48
+ ---
49
+
50
+ ## 🔧 Repo-Specific Overrides & Constraints
51
+
52
+ ### Package Structure
53
+ - Two packages: `src/frontend` and `src/cli`. Both must maintain explicit `__all__` in their `__init__.py`.
54
+ - Runtime version is exported in `src/__init__.py` as `__version__: Final[str] = "1.0.0"`.
55
+ - CLI entry point: `eigenscribe = "cli.main:main"` in `pyproject.toml` under `[project.scripts]`.
56
+ - CLI is also runnable via `python -m cli` (see `src/cli/__main__.py`).
57
+
58
+ ### Color Palette Constraint
59
+ - **Single source of truth:** `COLOR_PALETTE` in `src/frontend/colors.py` is the canonical dictionary for all named color variables across the repository.
60
+ - All color variables must reference valid key names from `COLOR_PALETTE` or be defined as canonical 6-digit hex (`#rrggbb`).
61
+ - Never hardcode raw or inconsistent RGB values in downstream modules without a canonical hex reference.
62
+ - Use `hex_to_rgb()` from `src/frontend/colors.py` for deterministic hex-to-RGB conversion for ANSI escapes.
63
+
64
+ ### Gradient Engine
65
+ - Multi-stop gradients in `src/frontend/gradients.py` scale keyframe segments by the Golden Ratio ($\phi \approx 1.618$).
66
+ - Presets are defined in `GRADIENT_PRESETS` and should be extended rather than duplicated.
67
+
68
+ ### Test Structure
69
+ - Unit tests: `tests/unit/test_*.py` (isolated module tests).
70
+ - Functional tests: `tests/func/test_*.py` (CLI end-to-end workflows and integration scenarios).
71
+ - Shared fixtures: `tests/conftest.py`.
72
+ - Target **70%+ coverage** on `src/frontend` and `src/cli`.
73
+
74
+ ### Documentation (When Applicable)
75
+ - Sphinx + Read the Docs + Diátaxis documentation (`docs/source/`, `.readthedocs.yaml`) is **not yet set up** for this repository. When documentation infrastructure is added, follow the universal guidelines in the system prompt (Section 4.5).
76
+ - `README.md` and `CHANGELOG.md` serve as the primary documentation until Sphinx is configured.
77
+
78
+ ### Sublime Text Theme
79
+ - The `sublime-theme/` directory contains a Sublime Text 4 package (theme, color scheme, PreTeXt syntax & snippets). Keep its color scheme synchronized with `COLOR_PALETTE` in `src/frontend/colors.py`.
80
+
81
+ ---
82
+
83
+ ## 🏛️ Standards & Provenance
84
+
85
+ Software architecture, packaging governance, testing standards, branching discipline, and scientific parameter validation across this workspace are adapted from the CERFACS COOP engineering standards. Local HTML archives reside in `docs/COOP_blog/`.
86
+
87
+ ---
88
+
89
+ _🔬 Eigenscribe Inc. & Scriber Labs 2025–2026. Part of the Scriber Labs Research Framework._
@@ -0,0 +1,213 @@
1
+ ---
2
+ name: cosmic-visual-styling
3
+ description: Guidelines, design tokens, color palettes, and code recipes for applying the Eigenscribe / Sephirah cosmic visual theme, gradients, colormaps, and glassmorphic UI components across Python, CSS, and dashboards.
4
+ ---
5
+
6
+ ### 🌌 Cosmic Visual Styling & Sephirah Design System
7
+
8
+ Use this skill whenever designing, styling, or updating figures, scientific plots, data dashboards, CSS stylesheets, or CLI interfaces in the **Eigenscribe / Scriber Labs** workspace.
9
+
10
+ ---
11
+
12
+ ### 🎨 1. Canonical Cosmic & Sephirah Color Tokens
13
+
14
+ #### Surface & Void Foundations
15
+ - **Cosmic Center:** `#0a0f1f` — Deep celestial navy (radial center / primary card face).
16
+ - **Cosmic Mid / Void:** `#050812` — Intermediate cosmic gradient stop / dark canvas base.
17
+ - **Cosmic Pure Black:** `#000000` — Outer boundary void.
18
+ - **Standard Dark Slate:** `#0d1117` — Default Eigenscribe background foundation.
19
+ - **Standard Surface Panel:** `#161b22` — Default card / panel foundation.
20
+ - **Radial Cosmic Gradient:** `radial-gradient(circle at center, #0a0f1f 0%, #050812 60%, #000000 100%)`.
21
+
22
+ #### Luminous Sephirah Accents & Tooltips
23
+ - **Sephirah Ice-Cyan:** `#c8f8ff` — Ethereal highlight and high-contrast text accent.
24
+ - **Sephirah Translucent Glass:** `rgba(0, 232, 255, 0.08)` — Subtle frosted badge background.
25
+ - **Sephirah Ambient Glow:** `rgba(0, 232, 255, 0.25)` — Multi-layer box shadow and text glow.
26
+ - **Tooltip Backdrop:** `rgba(0, 0, 0, 0.7)` with `1px solid rgba(255, 255, 255, 0.1)` border and `backdrop-filter: blur(4px)`.
27
+
28
+ #### 🌌 Core EIGEN & 10 Sephirah Tree of Life Tokens
29
+ - **EIGEN Spectrum:**
30
+ - `cyan`: `#00e8ff` (0x00e8ff) — Primary Electric Cyan
31
+ - `sky`: `#14b5ff` (0x14b5ff) — Electric Sky Blue
32
+ - `blue`: `#3a98ff` (0x3a98ff) — Vibrant Cobalt Blue
33
+ - `purple`: `#7952f5` (0x7952f5) — Deep Cosmic Purple
34
+ - **10 Sephirah Tree of Life Nodes:**
35
+ - `0️⃣ Keter (Crown):` `#fff9d6` — Divine White-Gold
36
+ - `1️⃣ Chokhmah (Wisdom):` `#00ffff` — Pure Cyan
37
+ - `2️⃣ Binah (Understanding):` `#00e8ff` — Electric Cyan
38
+ - `3️⃣ Chesed (Mercy):` `#14b5ff` — Sky Blue
39
+ - `4️⃣ Gevurah (Severity):` `#0070eb` — Deep Royal Blue
40
+ - `5️⃣ Tiferet (Beauty):` `#ffd94a` (label `#4cc9f0`) — Radiant Gold / Solar Center
41
+ - `6️⃣ Netzach (Victory):` `#7952f5` — Electric Purple
42
+ - `7️⃣ Hod (Splendor):` `#5e17eb` — Deep Violet
43
+ - `8️⃣ Yesod (Foundation):` `#ff66b3` — Hot Pink / Astral Magenta
44
+ - `9️⃣ Malkuth (Kingdom):` `#038b00` — Deep Emerald Earth Green
45
+
46
+ #### ADHD Semantic High-Contrast Spectrum
47
+ - **Primary Cyan / Electric Blue (`#00e8ff` / `#14b5ff`):** Interactive focal points, active states, primary variables.
48
+ - **Secondary Violet (`#7952f5` / `#9b7dff`):** Structural markers, navigation layers, functions, subsections.
49
+ - **Tertiary Neon Green (`#22f792` / `#10b981`):** Success metrics, verified states, STEM/tech indicators, math constants (`#00f5db`).
50
+ - **Quaternary Coral / Amber (`#f78166` / `#ff783d`):** Warnings, dynamic parameters, auxiliary data, high-attention flags.
51
+ - **Pernary Hot Pink (`#ec4899` / `#ff40a1`):** Special modes, accents, and producer overrides.
52
+ - **4-Color Vibrant Accent Set:** Green (`#38fe52`), Blue (`#3881fe`), Magenta (`#fe38e4`), Amber (`#feb538`).
53
+
54
+ #### 🔮 Signature Gradient Sequences (Obsidian Notes Series)
55
+ - **`gradient_0` (Pure Cyan Flow):** `#00ffff` → `#00e8ff`
56
+ - **`gradient_1` (Cyan to Sky):** `#00ffee` → `#14b5ff`
57
+ - **`gradient_2` (Cyan to Royal Blue):** `#00e8ff` → `#0070eb`
58
+ - **`gradient_3` (Teal to Royal Blue):** `#03e8bd` → `#03b4e8` → `#0355e8`
59
+ - **`gradient_4` (Cyan to Deep Purple):** `#00e8ff` → `#14b5ff` → `#0a95eb` → `#0070eb` → `#5e17eb`
60
+ - **`gradient_5` (Cobalt to Violet):** `#00e8ff` → `#3a98ff` → `#0a95eb` → `#7952f5` → `#5e17eb`
61
+ - **`gradient_6` (Cyan to Hot Pink):** `#00e8ff` → `#14b5ff` → `#5280ff` → `#7952f5` → `#ff66b3`
62
+ - **`gradient_7` (Full Spectrum Flow):** `#00e8ff` → `#14b5ff` → `#5280ff` → `#7952f5` → `#ff66b3` → `#f78166`
63
+ - **`gradient_8` (Synthwave / Retrowave):** `#4cc9f0` → `#4361ee` → `#3a0ca3` → `#7209b7` → `#f72585`
64
+ - **`gradient_synthwave` (Reverse Synthwave):** `#f72585` → `#7209b7` → `#3a0ca3` → `#4361ee` → `#4cc9f0`
65
+
66
+ ---
67
+
68
+ ### 🐍 2. Python (Matplotlib, Pyplot & Seaborn) Recipes
69
+
70
+ Import and apply the centralized styling utilities from `frontend.the_scriber_experience`:
71
+
72
+ ```python
73
+ import matplotlib.pyplot as plt
74
+ import numpy as np
75
+ from boilerplates.python import (
76
+ THEME_TOKENS,
77
+ HIGH_CONTRAST_CYCLE,
78
+ apply_cosmic_theme,
79
+ apply_theme,
80
+ plot_eigenscribe_heatmap,
81
+ )
82
+
83
+ # 1. Activate Cosmic Deep Void Theme
84
+ apply_cosmic_theme(seaborn=True)
85
+
86
+ # 2. Render High-Contrast Trajectories
87
+ x = np.linspace(0, 10, 200)
88
+ fig, ax = plt.subplots(figsize=(8, 4.5))
89
+ ax.plot(x, np.sin(x), color=THEME_TOKENS["sephirah_cyan"], linewidth=2.2, label="Sephirah Phase $\\theta(t)$")
90
+ ax.plot(x, np.cos(x) * 0.75, color=THEME_TOKENS["primary"], linewidth=2.0, label="Carrier Signal")
91
+ ax.set_title("Cosmic Trajectory Dynamics", fontsize=12, fontweight="bold", pad=12)
92
+ ax.legend(framealpha=0.85)
93
+ plt.tight_layout()
94
+ plt.show()
95
+
96
+ # 3. Render Deep Cosmic Heatmap Matrix
97
+ matrix = np.random.default_rng(42).uniform(0, 1, size=(10, 10))
98
+ fig_heat, ax_heat = plt.subplots(figsize=(6, 5))
99
+ plot_eigenscribe_heatmap(
100
+ matrix,
101
+ style="cosmic_sephirah",
102
+ ax=ax_heat,
103
+ title="Cosmic Sephirah Coherence Matrix",
104
+ cbar_label="Intensity Level",
105
+ )
106
+ plt.tight_layout()
107
+ plt.show()
108
+ ```
109
+
110
+ ---
111
+
112
+ ### 📊 3. Plotly & Dash Dashboard Recipes
113
+
114
+ ```python
115
+ from boilerplates.python import (
116
+ COLOR_BG_COSMIC,
117
+ COLOR_SEPHIRAH_CYAN,
118
+ COLOR_TEXT_BRIGHT,
119
+ COLOR_TEXT_MUTED,
120
+ create_plotly_base_figure,
121
+ )
122
+
123
+ fig = create_plotly_base_figure("Cosmic Phase Dashboard", height=380)
124
+ fig.update_layout(
125
+ plot_bgcolor="rgba(10, 15, 31, 0.85)",
126
+ paper_bgcolor="rgba(0, 0, 0, 0)",
127
+ font=dict(color=COLOR_TEXT_MUTED, family="Aclonica, sans-serif"),
128
+ )
129
+ ```
130
+
131
+ ---
132
+
133
+ ### 🌐 4. CSS Glassmorphism & Sephirah Component Reference
134
+
135
+ All web layouts and dashboards must follow the 4-layer taxonomy defined in `house-rules/css-rules.md` and `boilerplates/css/tse-boilerplate.css`:
136
+
137
+ ```css
138
+ /* Deep Cosmic Radial Canvas */
139
+ .cosmic-canvas, body.cosmic-theme {
140
+ margin: 0;
141
+ overflow: hidden;
142
+ background: radial-gradient(
143
+ circle at center,
144
+ #0a0f1f 0%,
145
+ #050812 60%,
146
+ #000000 100%
147
+ );
148
+ font-family: 'Aclonica', sans-serif;
149
+ }
150
+
151
+ /* Glassmorphic Floating Tooltip */
152
+ #tooltip, .tooltip-glass {
153
+ position: absolute;
154
+ color: #ffffff;
155
+ background: rgba(0, 0, 0, 0.7);
156
+ padding: 6px 10px;
157
+ border-radius: 6px;
158
+ font-family: 'Aclonica', sans-serif;
159
+ pointer-events: none;
160
+ opacity: 0;
161
+ transition: opacity 0.2s ease;
162
+ z-index: 1000;
163
+ font-size: 12px;
164
+ border: 1px solid rgba(255, 255, 255, 0.1);
165
+ backdrop-filter: blur(4px);
166
+ }
167
+
168
+ /* ✨ Sephirah Luminous Labels ✨ */
169
+ @keyframes shimmer {
170
+ 0% { filter: brightness(1); }
171
+ 50% { filter: brightness(1.35); }
172
+ 100% { filter: brightness(1); }
173
+ }
174
+
175
+ .sephirah-label {
176
+ position: absolute;
177
+ color: #c8f8ff;
178
+ font-family: "Aclonica", sans-serif;
179
+ font-size: 14px;
180
+ letter-spacing: 1px;
181
+ text-align: center;
182
+ pointer-events: none;
183
+ user-select: none;
184
+ padding: 4px 10px;
185
+ border-radius: 14px;
186
+ backdrop-filter: blur(4px);
187
+ background: rgba(0, 232, 255, 0.08);
188
+ border: 1px solid rgba(255, 255, 255, 0.08);
189
+ text-shadow:
190
+ 0 0 5px currentColor,
191
+ 0 0 10px currentColor,
192
+ 0 0 20px currentColor;
193
+ box-shadow:
194
+ 0 0 8px rgba(0, 232, 255, 0.25),
195
+ inset 0 0 8px rgba(255, 255, 255, 0.04);
196
+ transform: translate(-50%, -50%);
197
+ z-index: 10;
198
+ animation: shimmer 4s infinite ease-in-out;
199
+ }
200
+ ```
201
+
202
+ ---
203
+
204
+ ### 💻 5. CLI 256-Color & ANSI Palettes
205
+
206
+ Use `frontend.the_scriber_experience.cli` for terminal color formatting:
207
+
208
+ - `eigen_cosmic_navy` (ANSI 17)
209
+ - `eigen_cosmic_void` (ANSI 16)
210
+ - `eigen_sephirah_cyan` (ANSI 123 / `#c8f8ff`)
211
+ - `eigen_cyan` (ANSI 51)
212
+ - `eigen_purple` (ANSI 129)
213
+ - `eigen_green_bright` (ANSI 41)
@@ -0,0 +1,58 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ### Added
11
+ - Comprehensive design tokens and gradient reference document in `docs/colors-and-gradients.md`.
12
+ - `theme`, `mermaid`, and `doctor` subcommands in `src/cli/main.py`.
13
+ - Re-exported `cli_group` in `src/cli/__init__.py` and `PRESETS` alias in `src/frontend/gradients.py`.
14
+ - New standard in `docs/workspace-setup-guide.md`: mandatory rule prohibiting duplicate file/folder names (case-insensitive and separator-normalized), with exceptions for `__init__.py` and `main.py`.
15
+ - AI-Generated Content Disclosure Standard in `docs/workspace-setup-guide.md` (section 4) — requiring disclosure notices, dedicated `docs/` placement, and README cross-references for AI-generated documentation.
16
+ - GitHub Actions release workflow (`.github/workflows/publish.yml`) that runs the test suite on Python 3.10–3.12, builds the sdist + wheel with `uv build` (with a wheel-import smoke test), and publishes to PyPI/TestPyPI via `uv publish` using Trusted Publishing (OIDC, no stored tokens); triggered by `vX.Y.Z` SemVer tag pushes or manual `workflow_dispatch`.
17
+ - `src/scriber_core/__init__.py` package root that exports `__version__` and re-exports the `frontend` and `cli` subpackages, establishing `scriber_core` as the single public import namespace.
18
+
19
+ ### Changed
20
+ - Collapsed multi-path `try/except ImportError` fallback chains across `src/frontend/gradients.py`, `src/frontend/the_scriber_experience/style/gradient_presets.py`, `src/frontend/the_scriber_experience/style/semantic_roles.py`, `src/frontend/the_scriber_experience/mermaid/theme.py`, `src/cli/main.py`, `src/cli/messaging.py`, and `src/cli/__main__.py` into canonical absolute imports (`frontend.*` and `cli.*`).
21
+ - Refactored `src/frontend/the_scriber_experience/style/gradient_presets.py` to import and re-export gradient presets directly from `frontend.gradients`.
22
+ - Updated CLI package exports and repointed all `cli.colors` consumers to `cli.colors_table`.
23
+ - Renamed `src/frontend/THE_SCRIBER_EXPERIENCE/` to `src/frontend/the_scriber_experience/` (PEP 8 compliant package naming).
24
+ - Updated all imports across `src/`, `boilerplates/`, and `tests/` to use `the_scriber_experience` instead of `THE_SCRIBER_EXPERIENCE`.
25
+ - Removed `sys.modules` aliasing hacks in `src/frontend/__init__.py` that bridged uppercase and lowercase import names.
26
+ - Removed try/except import fallback in `src/cli/main.py` that attempted `THE_SCRIBER_EXPERIENCE` before `the_scriber_experience`.
27
+ - Updated `pyproject.toml` console script entry point to `cli.main:main`.
28
+ - Updated `docs/workspace-setup-guide.md` to explicitly state `COLOR_PALETTE` in `src/frontend/colors.py` as the canonical source of truth with the repo-wide hex constraint.
29
+ - Renamed `src/frontend/the_scriber_experience/style/tse_colors.py` to `semantic_roles.py` to eliminate naming collision with `colors.py` in the parent directory.
30
+ - Renamed `src/frontend/the_scriber_experience/style/tse_gradients.py` to `gradient_presets.py` to eliminate naming collision with `gradients.py` in the parent directory.
31
+ - Moved `src/frontend/messaging.py` to `src/cli/messaging.py` — all CLI-specific terminal styling now lives in `src/cli/`.
32
+ - Consolidated the TSE/semantic/CLI/EIGEN color palettes (`TSE_COLORS`, `SEMANTIC_COLORS`, `CLI_COLORS`, `EIGEN_COLORS`, `EIGEN_NODE_COLORS`, `EIGEN_LABEL_COLORS`) into `src/frontend/colors.py`, making `src/frontend/colors.py` and `src/frontend/gradients.py` the sole source of truth for colors and gradients; repointed `src/cli/main.py`, `src/frontend/__init__.py`, and `src/frontend/the_scriber_experience/__init__.py` to them.
33
+ - Consolidated the two top-level packages into a single `scriber_core` namespace: moved `src/frontend/` → `src/scriber_core/frontend/` and `src/cli/` → `src/scriber_core/cli/`, repointed every import to `scriber_core.frontend.*` / `scriber_core.cli.*`, updated the console entry point to `scriber_core.cli.main:main`, the wheel packages to `["src/scriber_core"]`, and the CI wheel smoke test to `import scriber_core` — so the distribution no longer installs generic top-level `frontend`/`cli` packages that could collide with consumer projects.
34
+
35
+ ### Removed
36
+ - Deleted duplicate `src/cli/colors.py` facade in favor of direct `cli.colors_table` imports, establishing `src/frontend/colors.py` as the single owner of the `colors` module name.
37
+ - Deleted stray package marker `src/__init__.py` to eliminate ambiguous `src.`-prefixed imports and maintain `packages = ["src/frontend", "src/cli"]` parity.
38
+ - Removed `src/frontend/messaging.py` (moved to `src/cli/messaging.py`) — all CLI-specific terminal styling now lives in `src/cli/`.
39
+ - Removed deprecated `src/frontend/the_scriber_experience/cli/` directory and its contents (`__init__.py`, `gradients.py`, `main.py`, `messaging.py`), consolidating all CLI utilities into `src/cli/`.
40
+ - Removed hyphenated alias files `src/frontend/the_scriber_experience/style/tse-colors.py` and `tse-gradients.py` (these simply forwarded to `tse_colors.py` and `tse_gradients.py`).
41
+ - Removed `THE_SCRIBER_EXPERIENCE` export alias from `src/__init__.py` and `src/frontend/__init__.py`.
42
+ - Removed `boilerplates/python/gold-standard-boilerplate.py` (identical duplicate of `gold-standard.py`).
43
+ - Removed `house-rules/python-rules_v1.md` (content duplicate of `python-rules.md`).
44
+ - Removed `src/frontend/the_scriber_experience/style/plots/` forwarding bridge directory (no external imports; re-exported from `plots/`).
45
+ - Removed the `src/frontend/the_scriber_experience/style/` directory and its modules (`__init__.py`, `semantic_roles.py`, `gradient_presets.py`); the `semantic_roles.py` palettes now live in `src/frontend/colors.py` and `gradient_presets.py` was a redundant re-export of `src/frontend/gradients.py`.
46
+
47
+ ### Fixed
48
+ - Defined the previously missing `EIGEN_LABEL_COLORS` (referenced in imports and `__all__` but never defined) and corrected `src/cli/branding.py` to use `COLOR_PALETTE["node-2"]` instead of the non-existent `vivid_cyan` key — both defects had made the `frontend` and `cli` packages fail to import.
49
+ - Aligned `tests/unit/test_cli.py` and `tests/unit/test_cli_colors_table.py` with the actual public API (`run_cli_smoke_test`, `EIGENSCRIBE_BLOCK_TEXT`, `node-1`) and ANSI-stripped the `--version` assertions; the full suite passes (46 tests).
50
+
51
+ ## [1.0.0] - 2026-11-17
52
+
53
+ ### Added
54
+ - Core repository initialization with `src/frontend/` and `src/cli/` packages.
55
+ - 4-layer design token system with 67 primitive colors in `COLOR_PALETTE`.
56
+ - Multi-stop TrueColor gradient engine with Golden Ratio ($\phi \approx 1.618$) keyframe scaling.
57
+ - Comprehensive ANSI 256-color palette index, terminal swatches, and table formatter.
58
+ - Automated testing suite covering CLI commands, colors table, and messaging utilities.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 eigenscribe
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.