@pheem49/mint 1.9.0 → 1.10.0

package/temp_gridgeist/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+All notable changes to Gridgeist are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.2.0] - 2026-07-20
+
+### Added
+
+- Added a conditional system-contract reference covering semantic color,
+  typography, layout, spacing, component grammar, states, media, motion, and
+  proportional DESIGN.md interoperability.
+- Added paired English and Thai behavioral evaluation coverage for design-system
+  coherence and persistent-artifact boundaries.
+
+### Changed
+
+- Strengthened the core workflow and review checklist to reconcile existing
+  design-system sources, define reusable component rules, and review color/theming
+  and component coherence separately.
+- Clarified that product content alone cannot make an underspecified broad redesign
+  brand-derived, and prohibited system definition or implementation edits while its
+  direction remains provisional.
+- Made overlapping broad visual-skill ownership an explicit pre-thesis gate instead
+  of allowing the companion to be silently ignored or blended.
+- Documented optional DESIGN.md intake and output in the English and Thai usage
+  guidance without making it a dependency.
+
+## [1.1.2] - 2026-07-18
+
+### Added
+
+- Added compact companion coordination so Gridgeist remains the default owner of
+  product and visual direction without requiring optional context, asset, audit, or
+  verification capabilities.
+- Added paired English and Thai evaluation scenarios for overlapping art-direction
+  skills, internationalization and user preferences, interaction alternatives, and
+  bounded performance evidence.
+
+### Changed
+
+- Strengthened the review checklist for container resilience, language direction,
+  forced colors, unobscured focus, non-drag alternatives, media stability, and
+  evidence-bounded performance review.
+- Documented optional companion workflows and role boundaries in the English and
+  Thai READMEs without making them installation dependencies.
+
+## [1.1.1] - 2026-07-18
+
+### Added
+
+- Added isolated live smoke tests for Codex plugin clean installation, marketplace
+  refresh, reinstall, and universal installer updates on release tags and manual CI
+  runs.
+- Added a bilingual direction-decision fixture, paired ambiguous/explicit scenarios,
+  and preserved raw regression outputs for the new collaboration boundary.
+
+### Changed
+
+- Reordered the English and Thai Quickstarts so the Codex plugin and universal
+  installer lead, with repository cloning and manual copying kept as fallback.
+- Added a conditional direction-alignment gate for broad, underspecified Create and
+  Redesign work without slowing explicit directions, Reviews, or narrow repairs.
+
+## [1.1.0] - 2026-07-16
+
+### Added
+
+- Added explicit update instructions for Codex plugins, `npx skills`, Git clones,
+  and manual installations in English and Thai documentation.
+- Added dependency-free release validation and GitHub Actions checks for skill,
+  plugin, marketplace, documentation, and bilingual evaluation alignment.
+
+### Changed
+
+- Reframed Gridgeist around product-native structure so grids may be visible,
+  quiet, or invisible according to the established brand.
+- Added explicit adaptation guidance for image-led, playful, technical,
+  content-heavy, and transactional interfaces.
+- Added interaction-state inventory, verification evidence, and claim-integrity
+  requirements to the core workflow and review checklist.
+- Strengthened behavioral evaluation guidance with repeat runs,
+  scenario-level evidence, implementation checks, and trigger boundaries.
+- Made the documented Windows validation command explicitly use UTF-8.
+- Pinned the public marketplace entry to the v1.1.0 release tag.
+
+## [1.0.1] - 2026-07-14
+
+### Fixed
+
+- Added a Git-backed Codex marketplace catalog for two-command installation.
+- Moved the installable skill to the standard `skills/gridgeist/` plugin path
+  so Codex plugin validation and marketplace installation use the same source.
+
+## [1.0.0] - 2026-07-13
+
+Gridgeist's first stable release.
+
+### Added
+
+- A reproducible Tracefield case study with the original baseline, exact prompt,
+  six-part rubric, verification evidence, and stated limitations.
+- A dedicated case-study page and a field-proof section on the project website.
+- Direct links from the English and Thai documentation to the live Tracefield
+  interface and its source repository.
+
+### Changed
+
+- Promoted the Codex plugin manifest from `0.1.0` to `1.0.0` to mark the public
+  skill interface and its Create, Redesign, and Review workflows as stable.
+
+## [0.1.0] - 2026-07-13
+
+### Added
+
+- Initial Gridgeist agent skill with Create, Redesign, and Review workflows.
+- Codex plugin manifest and agent-facing interface metadata.
+- English and Thai documentation and evaluation prompts.
+- Interactive examples and a responsive GitHub Pages website.
+
+[Unreleased]: https://github.com/ohmiler/gridgeist/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/ohmiler/gridgeist/compare/v1.1.2...v1.2.0
+[1.1.2]: https://github.com/ohmiler/gridgeist/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/ohmiler/gridgeist/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/ohmiler/gridgeist/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/ohmiler/gridgeist/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/ohmiler/gridgeist/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/ohmiler/gridgeist/releases/tag/v0.1.0

package/temp_gridgeist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/temp_gridgeist/README.md

@@ -0,0 +1,323 @@
+<p align="center">
+  <img src="skills/gridgeist/assets/gridgeist.svg" alt="Gridgeist agent skill for web interface direction" width="240" />
+</p>
+
+# Gridgeist
+
+**English** · [ภาษาไทย](README.th.md) · [Website](https://ohmiler.github.io/gridgeist/) · [Examples](https://ohmiler.github.io/gridgeist/examples/)
+
+Gridgeist is an agent skill for creating, redesigning, and reviewing product-native web interfaces. It adapts structure, typography, imagery, interaction, and product evidence to the established brand, using grids as visible, quiet, or invisible logic. It helps agents move beyond generic AI-generated SaaS patterns while preserving product intent, behavior, responsiveness, and accessibility.
+
+## See the difference
+
+This illustrative Northline logistics comparison is rendered from two full HTML/CSS pages with the same product, copy, sample operating data, and viewport. The After page and screenshot were rebuilt with the **Gridgeist v1.2.0** system workflow; Northline and all displayed data are fictional.
+
+<table>
+  <tr>
+    <th width='50%'>Without Gridgeist - generic SaaS</th>
+    <th width='50%'>With Gridgeist v1.2.0 - product-native system</th>
+  </tr>
+  <tr>
+    <td><img src='docs/assets/northline-before.png' alt='Generic Northline logistics landing page with centered marketing copy, rounded controls, a chart, and interchangeable metric cards' width='100%' /></td>
+    <td><img src='docs/assets/northline-after.png' alt='Gridgeist v1.2.0 Northline concept organized as one operational system with live freight topology, semantic lane states, arrival times, and an explicit priority exception' width='100%' /></td>
+  </tr>
+</table>
+
+Same content and sample operating data; a different design system. Gridgeist turns the topology, route table, exception, actions, and metrics into one connected operational surface built from product evidence, while labeling the concept honestly. Both README images are browser captures of the working pages. [Open the Before page](https://ohmiler.github.io/gridgeist/readme-showcase/?view=before) or [open the v1.2.0 After page](https://ohmiler.github.io/gridgeist/readme-showcase/?view=after&rev=ab77ceb6).
+
+## What v1.2.0 changes
+
+Gridgeist now treats visual decisions as one system, not a sequence of isolated styling choices.
+
+| Area | v1.2.0 behavior |
+| --- | --- |
+| System contract | Defines color, typography, layout, spacing, shape, components, states, media, and motion as one compact direction before implementation. |
+| Semantic roles | Connects foundation tokens to semantic roles and component decisions, so contrast and state relationships remain intentional. |
+| Component grammar | Gives related controls and content shared anatomy, variants, density, states, and content-stress rules instead of styling each instance separately. |
+| Direction safety | When the visual thesis is still broad, offers distinct directions and waits for alignment before committing tokens or editing the interface. |
+| Skill coordination | Names one direction owner when multiple UI skills are active, preventing competing visual systems. |
+| Verification | Checks representative widths, overflow, focus, interaction states, themes, and reduced motion—and limits claims to observed evidence. |
+
+In practice, the result is more coherent, less generic, and easier to extend without losing the product's identity. The v1.2.0 release was exercised through three English and three Thai system-contract scenarios, independent responsive browser checks, and repaired guardrail tests.
+
+## 60-second Quickstart
+
+1. Install Gridgeist through the primary channel for your agent.
+
+   For Codex, add the Git marketplace and install the plugin:
+
+   ```powershell
+   codex plugin marketplace add ohmiler/gridgeist
+   codex plugin add gridgeist@gridgeist
+   ```
+
+   For Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and other compatible agents, use the universal installer:
+
+   ```powershell
+   npx skills add ohmiler/gridgeist -g
+   ```
+
+   **Manual fallback:** If neither installer is available, continue to [Manual installation](#manual-installation).
+2. Start a new agent session in your web project and paste:
+
+   ```text
+   Use the Gridgeist skill to review this interface without editing it yet. Give me a one-line verdict, prioritized findings with evidence, and one coherent redesign direction. Preserve the product's behavior and brand.
+   ```
+
+Agents that support explicit skill invocation can use `$gridgeist` in the prompt. Continue to [Installation](#installation) for product-specific details and more examples.
+
+## Use cases
+
+- Create a distinctive landing page, dashboard, documentation site, portfolio, or learning platform.
+- Redesign an existing interface without breaking its behavior or brand.
+- Review a draft and prioritize hierarchy, composition, responsiveness, accessibility, and implementation quality.
+- Adapt technical, editorial, image-led, playful, utilitarian, or visible-grid direction without erasing the brand.
+
+## Installation
+
+### Codex plugin
+
+This repository is packaged as a Codex plugin through [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json). The plugin points to the same `skills/gridgeist/` directory used by the other channels, so all installations share one source of truth.
+
+Add the Gridgeist marketplace, then install the plugin:
+
+```powershell
+codex plugin marketplace add ohmiler/gridgeist
+codex plugin add gridgeist@gridgeist
+```
+
+Start a new Codex session after installation so the bundled skill is discovered.
+
+### Universal installer
+
+For Claude Code, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and other compatible agents, install Gridgeist with the [open agent skills CLI](https://github.com/vercel-labs/skills):
+
+```powershell
+npx skills add ohmiler/gridgeist -g
+```
+
+The installer discovers `skills/gridgeist/` and prompts you to choose the target agents. To select one directly, pass its agent name; for example:
+
+```powershell
+npx skills add ohmiler/gridgeist -g -a claude-code
+```
+
+### Manual installation
+
+Use manual copying only when the plugin and universal installer are unavailable:
+
+```powershell
+git clone https://github.com/ohmiler/gridgeist.git
+Copy-Item -Recurse .\gridgeist\skills\gridgeist "$HOME\.agents\skills\gridgeist"
+```
+
+For a different agent, copy `skills/gridgeist/` to that product's skills directory. The agent must support the Agent Skills `SKILL.md` convention. Discovery and invocation behavior can differ between products. Start a new agent session after copying the directory.
+
+## Updating
+
+Gridgeist releases do not update silently. Use the command for the channel that installed the skill, then start a new agent session.
+
+### Codex plugin
+
+Refresh the Git-backed marketplace snapshot, then reinstall the plugin version exposed by that release:
+
+```powershell
+codex plugin marketplace upgrade gridgeist
+codex plugin add gridgeist@gridgeist
+```
+
+Confirm the installed version with `codex plugin list`. If the current session still uses older instructions, start a new thread or restart the Codex app.
+
+### Universal installer
+
+Update a global Gridgeist installation:
+
+```powershell
+npx skills update gridgeist -g -y
+```
+
+For a project-scoped installation, use `npx skills update gridgeist -p -y` instead.
+
+### Git clone or manual copy
+
+Run `git pull --ff-only` in an existing clone, then reinstall from `skills/gridgeist/`. Manual copies do not retain source or version metadata, so replace the complete skill directory from a tagged release. Prefer the Codex plugin or universal installer when future updates matter.
+
+## Example prompts
+
+Invoke Gridgeist directly with `$gridgeist` and include four essentials:
+
+1. The product and its audience.
+2. The mode: create, redesign, or review.
+3. What must be preserved, such as behavior, brand color, or content.
+4. What must be verified, such as desktop, mobile, keyboard, and accessibility.
+
+```text
+Use $gridgeist to redesign this Next.js course landing page. Preserve all behavior and the blue brand color, but replace the generic SaaS cards with an editorial grid and verify desktop and mobile layouts.
+```
+
+```text
+Review this dashboard with $gridgeist. Give me a one-line verdict, prioritized findings with evidence, and a coherent replacement direction before editing.
+```
+
+```text
+Use $gridgeist to create a technical documentation homepage where real API examples and navigation structure carry the visual identity.
+```
+
+### Brief for a closer match
+
+For a more precise result, provide these details when they are relevant:
+
+- **Product and audience** — what the product does and who uses it.
+- **Primary task** — the most important thing the user must accomplish.
+- **Direction** — the intended character, such as warm editorial, precise
+  technical, or playful tactile.
+- **Authentic material** — product UI, data, prose, imagery, artwork, code, or a
+  workflow that should carry visual weight.
+- **Preserved constraints** — brand signals, content, routes, behavior, components,
+  privacy, or platform requirements that must not change.
+- **Exclusions** — visual language or behavior that would be wrong for the product.
+- **Flows and states** — the important default, loading, empty, error, success,
+  disabled, and destructive paths.
+- **Verification** — representative viewports, keyboard, touch, focus, overflow,
+  reduced motion, and primary flows to exercise.
+
+When the direction is already clear, state it and let Gridgeist proceed without
+another aesthetic questionnaire. When several materially different directions are
+still credible, ask Gridgeist to inspect first, offer two or three grounded options
+with trade-offs and a recommendation, and wait for alignment before editing.
+
+Copy and adapt this template:
+
+```text
+Use $gridgeist to [create / redesign / review] [page or product surface].
+
+Product and audience:
+[What it does and who uses it]
+
+Primary task:
+[The most important user outcome]
+
+Direction:
+[A confirmed direction, or: Inspect first, propose two or three grounded
+directions with trade-offs and a recommendation, and do not edit until I choose.]
+
+Authentic material that should lead:
+[Product UI / data / prose / imagery / artwork / code / workflow]
+
+Preserve:
+[Brand, content, routes, behavior, components, and constraints]
+
+Avoid:
+[Visual language or behavior that would be wrong]
+
+Important flows and states:
+[Primary flow and applicable default/loading/empty/error/success/disabled states]
+
+Verify:
+[Viewports, keyboard, touch, focus, overflow, reduced motion, and primary flow]
+
+Inspect the repository and rendered interface before taking action.
+```
+
+Describe outcomes and genuine constraints rather than prescribing a CSS recipe.
+Unless they are established brand requirements, leave font sizes, spacing, radii,
+shadows, and column counts for Gridgeist to derive as one coherent system.
+
+If a project already contains a `DESIGN.md`, theme, token set, or component
+library, Gridgeist inspects it alongside the implementation and rendered interface
+instead of assuming the sources agree. `DESIGN.md` is optional interoperability,
+not a dependency: Gridgeist should not create or update one unless you request a
+portable design-system artifact or explicitly include durable system documentation
+in the work.
+
+Gridgeist also allows implicit invocation when the agent recognizes a matching web-interface task.
+
+## Working with companion skills
+
+Gridgeist works best as the sole owner of product and visual direction, with optional companion skills supplying context, technical review, or rendered evidence. The lightest recommended workflow for most projects is:
+
+```text
+Gridgeist -> Playwright
+```
+
+Gridgeist defines the interface thesis, hierarchy, system, and implementation direction. Playwright then checks the rendered result across representative viewports and interactions; it can also provide repeatable [visual comparisons](https://playwright.dev/docs/test-snapshots).
+
+| Situation | Recommended workflow | Division of responsibility |
+| --- | --- | --- |
+| Most web projects | `Gridgeist -> Playwright` | Design and implementation, then rendered verification |
+| Figma is the source of truth | `Figma -> Gridgeist -> Playwright` | Extract components, variables, and layout context; adapt them to the product and codebase; verify the result. See the [Figma MCP server](https://developers.figma.com/docs/figma-mcp-server/). |
+| React or Next.js | `Gridgeist -> Vercel React Best Practices -> Playwright` | Own the interface direction; review framework performance; verify behavior. See [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills). |
+| Pre-release quality audit | `Gridgeist -> Web Quality Audit -> Playwright` | Review hierarchy and brand fit; audit accessibility, performance, SEO, and web quality; confirm the live result. See [Web Quality Skills](https://github.com/addyosmani/web-quality-skills). |
+| Original imagery is required | `Gridgeist -> image generation -> Gridgeist -> Playwright` | Establish the thesis before generating assets, compose with the selected assets, then verify the interface. |
+
+Treat these as optional workflows, not dependencies. Add only the companion that answers a real need, and keep another broad frontend-design or art-direction skill out of the same design phase; competing visual priors can weaken a coherent result. Companion skill names and availability vary between agents.
+
+Example:
+
+```text
+Use $gridgeist to redesign this interface while preserving its behavior and brand.
+After implementation, use Playwright to verify representative desktop and mobile
+viewports, keyboard interaction, overflow, and the primary user flow.
+```
+
+## Repository layout
+
+```text
+.codex-plugin/
+  plugin.json          Codex plugin manifest
+skills/gridgeist/      Installable skill
+  SKILL.md             Trigger conditions and core workflow
+  agents/openai.yaml   Agent-facing interface metadata
+  references/          Design language and review checklist
+evals/prompts.md       Repeatable manual behavior checks
+docs/                  Design and implementation records
+```
+
+## Case studies
+
+[Tracefield](https://ohmiler.github.io/tracefield/) applies Gridgeist to a working developer-observability dashboard. Its [repository](https://github.com/ohmiler/tracefield) preserves the generic baseline, exact prompt, evaluation rubric, tested trace domain, and responsive final interface.
+
+[Ledgerline](https://ohmiler.github.io/ledgerline/) tests the same skill on dense payment API documentation. Its [repository](https://github.com/ohmiler/ledgerline) preserves a conventional baseline, exact prompt, six-part rubric, deterministic API content, four viewport checks, and the responsive final interface.
+
+[Morrow](https://ohmiler.github.io/morrow-portfolio/) stress-tests brand adaptation with a fictional image-led creative portfolio. Its [repository](https://github.com/ohmiler/morrow-portfolio) preserves shared AI-generated artwork, a conventional baseline, exact prompts, a six-part rubric, four viewport checks, and a final interface deliberately unlike the technical case studies.
+
+[Doodlewood](https://ohmiler.github.io/doodlewood/) tests playful interaction design with a fictional, privacy-preserving children's drawing studio. Its [repository](https://github.com/ohmiler/doodlewood) preserves the generic baseline, exact prompt, six-part rubric, local drawing engine, four viewport checks, and explicit limits around child safety and real-user evidence.
+
+Together, the four self-produced case studies cover data-heavy, content-heavy, image-led, and playful interactive surfaces. Further validation should now prioritize independent users, agents, and projects rather than adding another first-party visual category.
+
+## Limitations
+
+- Output quality depends on the agent inspecting the actual repository and rendered interface.
+- Automated checks do not replace visual inspection at representative viewport sizes.
+- The suggested defaults are starting points, not a mandatory preset for every brand.
+- Model outputs are not deterministic. Re-run evaluations when the skill or target agent changes.
+
+## Validation
+
+Validate the installable skill structure:
+
+```powershell
+python -X utf8 "$HOME\.codex\skills\.system\skill-creator\scripts\quick_validate.py" .\skills\gridgeist
+```
+
+Check release metadata and bilingual documentation without external dependencies:
+
+```powershell
+python -X utf8 .\scripts\validate_release.py
+```
+
+Exercise clean installation and updates through the live Codex marketplace and universal installer. This check requires Codex, Node.js, npm, Git, and network access; it uses temporary homes and does not modify your existing installations.
+
+```powershell
+python -X utf8 .\scripts\smoke_test_install.py
+```
+
+Behavioral evaluation prompts are in [`evals/prompts.md`](evals/prompts.md).
+
+## Contributing
+
+Keep `SKILL.md` concise and place detailed, conditionally loaded guidance in `references/`. For behavior changes, update an evaluation scenario and record what failed before changing the skill. Open an issue or pull request with the motivating prompt and observed output.
+
+## License
+
+[MIT](LICENSE)