Checkpoint from VS Code for cloud agent session

.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+site/.svelte-kit/
+site/build/
+.env
+.env.*
+!.env.example
+.claude/settings.local.json
+.cloudflared.log
+.localtunnel.log
+.wrangler/

agent-sandbox/README.md

@@ -0,0 +1,17 @@
+# Agent Sandbox
+
+This directory is for testing, prototyping, and debugging agent workflows, patches, and automation scripts in isolation from the main VeloraCSS codebase.
+
+## Usage
+- Place test scripts, agent instructions, and workflow prototypes here.
+- Use for rapid iteration and validation before applying changes to production code.
+
+## Structure
+- /scripts: automation and patch scripts
+- /tests: workflow and patch test cases
+- /instructions: agent prompt and skill files
+
+## Guidelines
+- Keep sandbox experiments isolated.
+- Clean up obsolete files regularly.
+- Document any reusable patterns or lessons learned.

agent-sandbox/backup/README.md

@@ -0,0 +1,45 @@
+# VeloraCSS Monorepo
+
+VeloraCSS is a modular CSS framework and ecosystem, organized as a monorepo for easy development, integration, and deployment.
+
+## Structure
+
+This repository contains:
+
+- **packages/veloracss/** — Core VeloraCSS framework source
+- **packages/tracker/** — Project tracker and Discord integration
+- **packages/brand/** — Design assets and branding
+- **packages/docs/** — Documentation site and guides
+
+## Getting Started
+
+1. **Install dependencies**
+   - Use `npm install` or your preferred workspace tool (pnpm, Yarn).
+
+2. **Develop**
+   - Work on any package in `packages/`.
+   - Each package has its own README and scripts.
+
+3. **Build & Test**
+   - Run build/test scripts from the root or individual package folders.
+
+## Monorepo Management
+
+- Use workspace tools (npm workspaces, pnpm, Yarn) for cross-package development.
+- All packages share a single git history.
+
+## Contributing
+
+- Fork the repo and submit PRs for any package.
+- See individual package READMEs for details.
+
+## License
+
+MIT License. See LICENSE file for details.
+
+---
+
+For more information, visit:
+- [VeloraCSS Tracker](https://github.com/VeloraCSS/tracker)
+- [VeloraCSS Brand](https://github.com/VeloraCSS/brand)
+- [VeloraCSS Docs](https://github.com/VeloraCSS/docs)

agent-sandbox/backup/TODO.md

@@ -0,0 +1,233 @@
+# VeloraCSS NPM Publishing
+
+- Put together a step-by-step lifecycle from idea → published package → maintenance.
+- Included concrete tasks, tools, and “when to do it” guidance so you’re not guessing.
+- Added example package.json and a GitHub Actions publish workflow you can adapt.
+- Included ready-made AI prompts to ask for focused help at each stage.
+
+High-level phases (overview)
+1. Plan & design (foundation)
+2. Build the core (utilities, tokens, components)
+3. Tooling & build system
+4. Docs/demo site & examples
+5. Testing & quality (visual, unit, accessibility, perf)
+6. Release & publish (npm / GitHub)
+7. Maintain, iterate, support, and grow
+
+Detailed A → Z roadmap
+
+Phase 1 — Plan & design (before you write code)
+- Decide scope & goals
+  - Utility-first (like Tailwind) or component-first (like Bootstrap) or hybrid.
+  - Target audience: designers, devs, internal design system, public package.
+  - Browser support, accessibility standards, CSS-in-JS support, theming.
+- Design tokens & naming conventions
+  - Establish colors, spacing, typography, radii, z-index, opacity, etc.
+  - Store tokens in a source format (JSON, YAML) that drives builds.
+- Decide architecture
+  - Source: plain CSS / PostCSS / Sass / Less / CSS-in-JS / TypeScript-based generators.
+  - Distribution: precompiled CSS file(s) + optional JS for behavior (dropdowns, toggles).
+- Minimum initial deliverables
+  - Core utilities for spacing, colors, typography.
+  - 5–10 starter components (buttons, forms, cards, nav, container).
+  - README with usage examples and a demo site.
+
+Phase 2 — Build the core
+- Create a repo structure (suggested)
+  - src/
+    - tokens/ (colors.json, spacing.json)
+    - utilities/ (atomic CSS source or generator code)
+    - components/ (component styles, markup examples)
+    - themes/ (theme token overrides)
+  - dist/ (compiled, published artifacts)
+  - site/ or docs/ (demo & docs source)
+  - scripts/ (build scripts, audit)
+  - package.json, README.md, LICENSE, API_SURFACE.md
+- Implementation approach options
+  - Utility-first generator (PostCSS + plugin or custom JS) → emits atomic classes like .m-4, .text-primary
+  - Sass/SCSS with mixins and maps driven by tokens
+  - A code generator in Node (like the veloracss approach that compiles dist artifacts)
+- Start small and iterate: build utilities first, then compose components from utilities.
+
+Phase 3 — Tooling & build system
+- Tools to consider (pick what fits your approach):
+  - Bundlers/builders: esbuild, Vite, Rollup
+  - CSS tooling: PostCSS, lightningcss, Tailwind JIT-like generator (if utility-first)
+  - Preprocessors: Sass if you prefer scss
+  - Linting: stylelint for CSS, eslint for JS
+- Build tasks
+  - npm run build → creates dist/velora.css, dist/velora.min.css, dist/manifest.json
+  - npm run watch → development workflow
+  - npm run site:dev → runs docs/demo site locally
+- Exports & packaging
+  - Provide both CSS and JS entrypoints; include "style" field in package.json and an exports map.
+  - Provide optional compatibility layer (prefixed classes, older syntax) if needed.
+
+Example package.json (starter)
+```json name=example/package.json
+{
+  "name": "your-framework",
+  "version": "0.1.0",
+  "description": "Utility-first CSS framework with starter components",
+  "license": "MIT",
+  "main": "./dist/your-framework.js",
+  "style": "./dist/your-framework.css",
+  "files": ["dist", "README.md", "API_SURFACE.md"],
+  "scripts": {
+    "build": "node build.mjs",
+    "dev": "node dev.mjs",
+    "site:dev": "vite --config site/vite.config.js",
+    "test": "npm run lint && node test.mjs",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "stylelint": "^15.0.0"
+  }
+}
+```
+
+Phase 4 — Docs & demo site (do this early, not last)
+- Why start early: docs + examples are the best way to validate API and UX.
+- Choose a docs stack:
+  - Docusaurus, VitePress, Astro, or a SvelteKit / Next site for component demos.
+  - Storybook or Playroom for interactive components + visual testing.
+- Content to include:
+  - Quick start (install & include CSS)
+  - Usage examples for components & utilities
+  - API surface / manifest (what classes exist)
+  - Migration notes & changelog
+  - Playground or code pen embeds
+- When: as soon as first stable utilities + components exist. You can publish docs to GitHub Pages or static host while package is still pre-1.0.
+
+Phase 5 — Testing & quality control
+- CSS testing types:
+  - Visual regression: Percy, Chromatic, Playwright snapshot tests, or Puppeteer + diff
+  - Unit / regression tests: automated checks that style tokens compile correctly, class list coverage
+  - Accessibility: axe (axe-core, lighthouse), run tests on components
+  - Linting: stylelint rules, enforce design-token use
+- CI steps should include:
+  - install, build, lint, run tests, run docs audit (if you have audit scripts)
+  - run visual snapshot tests for key components
+- When: include tests before first public release; start with lint + unit checks, add visual tests as you add components.
+
+Phase 6 — Versioning & release strategy
+- Semantic versioning (SemVer):
+  - 0.x.y during early unstable phase. Breaking changes are expected.
+  - Use 1.0.0 to signal stable public API.
+- Release cadence:
+  - Pre-1.0: publish early, but mark as experimental and iterate quickly (0.1.0, 0.2.0…).
+  - Use pre-release tags (beta, alpha) when releasing unstable features: npm publish --tag beta
+- Changelog:
+  - Keep CHANGELOG.md or use conventional commits + semantic-release to auto-generate changelogs.
+
+Phase 7 — Publish to npm (timing & steps)
+- When to publish:
+  - Publish early if you want others to try it and you’re prepared to iterate quickly (pre-1.0).
+  - Publish after you have a usable dist/ build and clear README + quick-start.
+  - If you don’t want public use yet, keep private/unpublished until docs and tests are ready.
+- Steps to publish manually:
+  1. Create a package.json with "name", "version", "files", "style", etc.
+  2. Build dist (npm run build).
+  3. Verify package content: npm pack --dry-run
+  4. Login to npm: npm login (or use CI token)
+  5. npm publish --access public
+- CI (recommended): create a GitHub Action that runs tests and publishes on tag / release. Use the NPM_TOKEN secret.
+
+Example GitHub Actions publish workflow
+```yaml name=.github/workflows/publish-package.yml
+name: Publish package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test
+      - run: npm pack --dry-run
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+Phase 8 — After publishing: promotion & maintenance
+- Post-publish tasks:
+  - Create a GitHub release and attach release notes + changelog.
+  - Publish docs site to GitHub Pages or a static host.
+  - Share examples, starter templates, and code sandbox / stackblitz examples.
+- Maintenance:
+  - Review issues and PRs.
+  - Keep compatibility and migration guides.
+  - Automate security audits and dependency updates (Dependabot).
+
+Checklist before first public publish
+- [ ] README with quick start
+- [ ] LICENSE (MIT or other)
+- [ ] package.json fields: name, version, files, style, exports
+- [ ] Build script that creates dist/
+- [ ] npm pack dry-run passes
+- [ ] Basic tests (lint + simple build checks)
+- [ ] CHANGELOG or plan for changelog
+- [ ] NPM account + NPM_TOKEN secret for CI
+- [ ] Demo site or at least a demo/preview page
+
+Best practices & tips
+- Start small: publish a minimal but working set of utilities and examples.
+- Prefer machine-readable tokens (JSON) so you can generate CSS, docs, and theme variants automatically.
+- Provide both unminified and minified CSS for ease of debugging.
+- Use an exports map so consumers can import manifest or CSS path.
+- Accessibility: ensure form controls, focus states, color contrast.
+- Performance: keep the core small; consider generating only used classes for production (JIT-style) if possible.
+- Backwards compatibility: document breaking changes clearly and use migrations.
+
+Visual testing & QA suggestions
+- Storybook for components + Chromatic for visual diffing.
+- Playwright for end-to-end snapshots and critical path tests.
+- Use axe-core for automated accessibility checks in CI.
+
+How to use AI (ChatGPT) effectively — ready prompts
+- “Generate a list of utility classes and responsive variants for margin, padding, color, typography, and display for a utility-first CSS framework. Use BEM-style naming? No — use simple short utilities like m-4, p-2, text-primary.”
+- “Write a build.mjs script that compiles src/*.css via lightningcss and bundles JS with esbuild into dist/.”
+- “Create a starter README.md for a CSS framework called Velora with quick start, CDN example, npm install instructions, and usage examples for button, card, and form.”
+- “Write a GitHub Actions publish workflow that runs tests and publishes to npm on tags using NODE_AUTH_TOKEN.”
+- “Create a stylelint config and rules suitable for a utility-first CSS library and display sample lint errors and fixes.”
+- “Generate a minimal Docusaurus site config and a landing docs page with examples for nav, button, and typography.”
+
+Example question templates (paste & edit)
+- “I’ve implemented tokens in tokens/colors.json and utilities in src/utilities/; write an esbuild-based build.mjs that outputs dist/your.css and dist/your.js.”
+- “Given this tokens JSON (paste), produce SCSS variables and utility class generator code that outputs .text-{name} and .bg-{name} classes.”
+- “Write a Storybook story for my Button component including accessibility tests and a visual snapshot.”
+
+Two concrete starter choices (pick one)
+- Minimal static: PostCSS or Sass with a simple build script (fast, easy).
+- Modern generator: Node-based generator that reads tokens and emits CSS + manifest (more flexible; enables JIT or themed builds).
+
+If you want, I can:
+- Generate an initial repo scaffold (src, tokens, build scripts, README).
+- Create build.mjs using esbuild/lightningcss (like veloracss does).
+- Build a starter docs site with VitePress or Docusaurus and a demo page.
+- Create CI workflows for build/test/publish and show how to set NPM_TOKEN.
+
+What I need from you to proceed
+- Which architecture do you prefer? (Sass-based, PostCSS, or Node generator/utility-first)
+- Do you want a demo site with static examples (Docusaurus/VitePress) or interactive stories (Storybook)?
+- Are you ready to publish early (0.x) to npm, or do you want local/private validation first?
+
+Next steps (I’ll help hands-on)
+- Tell me which architecture or stack from above you prefer.
+- I’ll scaffold a repo with build scripts, a sample token set, a few utilities, and a docs site example — or
+- I’ll create the GitHub Actions workflow and a publish checklist tailored to your repo.
+
+Pick one option to start and I’ll scaffold the code and workflows you need.

agent-sandbox/instructions/architecture.agent.md

@@ -0,0 +1,18 @@
+# Architecture Agent
+
+name: architecture
+role: System Architect
+
+mission: Design and maintain the overall system architecture.
+
+responsibilities:
+  - Define system structure
+  - Document architecture decisions
+  - Maintain architectural diagrams
+  - Ensure scalability and maintainability
+
+instructions:
+  - Analyze requirements and constraints
+  - Design system components and interactions
+  - Document architecture in diagrams and docs
+  - Review architecture as features evolve

agent-sandbox/instructions/backend.agent.md

@@ -0,0 +1,18 @@
+# Backend Agent
+
+name: backend
+role: Backend Engineer
+
+mission: Build and maintain server-side logic and APIs.
+
+responsibilities:
+  - Implement business logic
+  - Design and build APIs
+  - Integrate with database
+  - Ensure security and scalability
+
+instructions:
+  - Develop server-side features
+  - Document API endpoints
+  - Optimize backend performance
+  - Maintain code quality and security

agent-sandbox/instructions/database.agent.md

@@ -0,0 +1,18 @@
+# Database Agent
+
+name: database
+role: Database Engineer
+
+mission: Design, implement, and maintain data storage systems.
+
+responsibilities:
+  - Design database schema
+  - Optimize queries
+  - Ensure data integrity
+  - Manage migrations
+
+instructions:
+  - Analyze data requirements
+  - Create and update schema
+  - Monitor and optimize performance
+  - Document database structure