@mohammadhprp/system-prompt 0.11.2 → 0.12.1

package/framework/agents/researcher.md

@@ -6,7 +6,7 @@ permission:
   bash: deny
   read: allow
   edit: deny
-  write: allow
+  write: deny
   patch: deny
   grep: allow
   glob: allow

package/framework/mcps/github-mcp/README.md

@@ -48,4 +48,4 @@ Relevant skills in this repository:
 
 - [`code-review`](../../skills/code-review/SKILL.md): reviewing pull request diffs.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for testing, debugging, and security review.
-- [`pull-request`](../../skills/pull-request/SKILL.md): preparing and submitting pull requests.
+- [`pr`](../../commands/pr.md): preparing and submitting pull requests.

package/framework/mcps/github-mcp/configs/.env.example

@@ -1 +1 @@
-GITHUB_TOKEN=
+GITHUB_PERSONAL_ACCESS_TOKEN=

package/framework/plugins/ponytail/README.md

@@ -41,4 +41,4 @@ Relevant skills in this repository:
 
 - [`code-review`](../../skills/code-review/SKILL.md): review backend changes for correctness and maintainability, complementary to ponytail's over-engineering focus.
 - [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for refactoring and behavior-preserving cleanup.
-- [`pull-request`](../../skills/pull-request/SKILL.md): prepare small, reviewable changes aligned with ponytail's minimal-diff philosophy.
+- [`pr`](../../commands/pr.md): prepare small, reviewable changes aligned with ponytail's minimal-diff philosophy.

package/framework/plugins/ponytail/capabilities.md

@@ -90,7 +90,7 @@ Or in `~/.config/ponytail/config.json` (`%APPDATA%\ponytail\config.json` on Wind
 - Use `/ponytail-review` after a coding session to catch over-engineering the agent missed.
 - Mark intentional shortcuts with `ponytail:` comments naming the ceiling and upgrade path.
 - Review `/ponytail-debt` regularly to track deferred improvements.
-- Pair with `code-review` and `pull-request` skills for a complete quality workflow.
+- Pair with `code-review` and the `/pr` command for a complete quality workflow.
 
 ## Common Workflows
 

package/framework/references/standards/pull-requests.md

@@ -39,4 +39,4 @@ Define reusable backend engineering rules for pull request decisions across proj
 ## Related Skills
 
 - `skills/code-review/SKILL.md`
-- `skills/pull-request/SKILL.md`
+- `commands/pr.md`

package/framework/skills/README.md

@@ -11,31 +11,31 @@ This catalog is framework-agnostic: each skill defines when to activate, a step-
 | [agent-browser](./agent-browser/SKILL.md) | Automate browser and Electron workflows for navigation, testing, screenshots, and data extraction. | Website interaction, browser automation, exploratory testing, QA, and Electron desktop app workflows. |
 | [backend-best-practices](./backend-best-practices/SKILL.md) | Consolidated backend engineering practices for API design, architecture, data, security, testing, observability, performance, debugging, and refactoring. | Any backend task that benefits from structured domain guidance across multiple backend disciplines. |
 | [brainstorming](./brainstorming/SKILL.md) | Turn ideas into fully formed designs and specs through collaborative dialogue before any implementation. | Starting a new feature, component, or project; any work that benefits from design before code. |
-| [brand-guidelines](./brand-guidelines/SKILL.md) | Apply Anthropic's official brand colors and typography to artifacts for company look-and-feel. | Styling artifacts with brand colors, typography, or visual design standards. |
 | [code-review](./code-review/SKILL.md) | Review backend changes for correctness, readability, maintainability, tests, performance, and security. | Reviewing pull requests, evaluating code quality, or mentoring. |
 | [codenavi](./codenavi/SKILL.md) | Investigate unfamiliar codebases with precision, implement surgically, and keep a `.notebook/` knowledge base that grows across sessions. | Fixing bugs, implementing features, refactoring, or investigating flows in unfamiliar territory. |
 | [create-adr](./create-adr/SKILL.md) | Create Architecture Decision Records (ADRs) that capture the context, decision, and consequences of significant architectural choices. | Documenting a finalized technical decision, or recording why a choice was made for future team members. |
 | [design-like-damien](./design/SKILL.md) | Apply premium, editorial-quality UI design philosophy and Lovable prompting system to produce interfaces that never look “AI-generated.” | Building apps, landing pages, or dashboards in Lovable; UI/UX design for premium SaaS, dark mode, typography, and scroll animations. |
 | [diagram-design](./diagram-design/SKILL.md) | Create technical and product diagrams as standalone HTML files with inline SVG and an opinionated editorial design system. | Architecture, data, process, and other diagrams that communicate more clearly than prose or tables. |
 | [docs-writer](./docs-writer/SKILL.md) | Write, review, and edit documentation files with consistent structure, tone, and technical accuracy. | Creating docs, reviewing markdown files, writing READMEs, or updating `/docs` directories. |
+| [effective-html](./effective-html/SKILL.md) | Create self-contained HTML artifacts with routed guidance for design, wireframes, prototypes, plans, and diagrams. | Standalone HTML reports, explainers, interfaces, wireframes, prototypes, plans, and diagrams. |
 | [find-skills](./find-skills/SKILL.md) | Discover, evaluate, and install skills from the open agent skills ecosystem. | Finding an installable skill for a specialized task or extending an agent's capabilities. |
 | [frontend-design](./frontend-design/SKILL.md) | Distinctive, intentional visual design for new UI or reshaping existing UI — aesthetic direction, typography, and choices that don't read as templated defaults. | Building new interfaces, reshaping existing UI, or escaping generic AI-generated design looks. |
+| [great-interface](./great-interface/SKILL.md) | Build, explain, review, and refine product interfaces across accessibility, layout, writing, typography, color, and UI polish. | Creating frontend interfaces, reviewing interface quality, explaining interface behavior, or comparing UI directions. |
 | [gitlab-mcp](./gitlab-mcp/SKILL.md) | Work with the GitLab MCP server tools for merge requests, issues, repositories, pipelines, and CI/CD workflows. | Any project hosted on GitLab (SaaS or self-hosted). |
 | [humanizer](./humanizer/SKILL.md) | Remove signs of AI-generated writing from text — inflated importance, promotional language, em dash overuse, rule of three, AI vocabulary, and filler phrases. | Editing or reviewing prose to make it sound more natural and human-written. |
 | [jira-mcp](./jira-mcp/SKILL.md) | Work with the Jira MCP server tools for issue management, JQL search, comments, and project inspection. | Any project using self-hosted Jira for issue tracking. |
 | [laravel-best-practices](./laravel-best-practices/SKILL.md) | Apply Laravel PHP patterns for Eloquent, validation, security, testing, caching, and architecture. | Writing, reviewing, or refactoring Laravel PHP code. |
 | [learning-opportunities](./learning-opportunities/SKILL.md) | Facilitate deliberate skill development during AI-assisted coding with short, optional interactive exercises. | After architectural work, schema changes, refactors, or when the user asks to understand code better. |
-| [lavish](./lavish/SKILL.md) | Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on. | Plans, comparisons, diagrams, tables, code diffs, or any output easier to grasp visually than as prose. |
 | [notion-mcp](./notion-mcp/SKILL.md) | Work with the Notion MCP server tools for pages, databases, comments, search, and workspace management. | Any project that uses Notion for documentation, tracking, or collaboration. |
 | [perf-web-optimization](./perf-web-optimization/SKILL.md) | Optimize web performance: bundle size, images, caching, lazy loading, and overall page speed. | A slow site, large bundles, layout shifts, poor Time to Interactive, or low Lighthouse scores. |
 | [security-best-practices](./security-best-practices/SKILL.md) | Perform language- and framework-specific security best-practice reviews and suggest improvements, with support for Python, JavaScript/TypeScript, and Go. | Explicit security reviews or reports, secure-by-default coding, or auditing existing code for major vulnerabilities. |
 | [sentry](./sentry/SKILL.md) | Inspect Sentry issues, summarize production errors, and pull health data via the Sentry API (read-only). | Checking production errors, summarizing recent crashes, or pulling a production error report. |
 | [show-me](./show-me/SKILL.md) | Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts. | Explaining logic, control flow, UI structure, file responsibility, or data flow with the smallest useful visual. |
-| [pull-request](./pull-request/SKILL.md) | Prepare small, reviewable changes with clear evidence, risk, deployment, and rollback notes. | Preparing PRs, writing descriptions, or planning safe deployments. |
 | [skill-creator](./skill-creator/SKILL.md) | Create new skills, modify and improve existing skills, and measure skill performance. | Designing new skills, optimizing existing skills, or running evals. |
 | [spec-driven-eval](./spec-driven-eval/SKILL.md) | Score how completely an implementation fulfills a PRD/spec, case by case, producing a single comparable final grade. | Benchmarking spec-driven implementations, grading acceptance criteria, or auditing implementation and test coverage against a spec. |
 | [technical-design-doc-creator](./technical-design-doc-creator/SKILL.md) | Create comprehensive Technical Design Documents (TDDs) with mandatory and optional sections through interactive discovery, in the user's language. | Writing a design doc, TDD, technical spec, or architecture document before implementing a significant change. |
 | [tlc-spec-driven](./tlc-spec-driven/SKILL.md) | Feature planning and implementation with adaptive phases, EARS testable requirements, atomic Conventional Commits, and independent verification. | Planning features, implementing with verification and atomic commits, or validating an implementation against a spec. |
+| [taste](./taste/SKILL.md) | Unified design-quality skill spanning anti-slop frontend design, image generation and image-to-code, brand kits, minimalist and industrial UI, redesigns, and Google Stitch design systems. | Landing pages, portfolios, redesigns, website/mobile/brand imagery, or any UI that must not look AI-generated. |
 | [web-design-guidelines](./web-design-guidelines/SKILL.md) | Review UI code for Web Interface Guidelines compliance — accessibility, focus, forms, animation, typography, and interaction patterns. | Reviewing UI, checking accessibility, auditing design or UX, or checking a site against best practices. |
 
 ## How Skills Are Organized

package/framework/skills/diagram-design/SKILL.md

@@ -192,7 +192,7 @@ Universal building blocks. Type-specialized primitives (lifeline, activation bar
 
 - Editorial callouts → [primitive-annotation.md](references/primitive-annotation.md)
 - Hand-drawn variant → [primitive-sketchy.md](references/primitive-sketchy.md)
-- Icon set (laptop, server, DB, K8s, Docker, AWS, …) → [primitive-icons.md](references/primitive-icons.md). Browse the gallery at [`assets/icons.html`](../assets/icons.html).
+- Icon set (laptop, server, DB, K8s, Docker, AWS, …) → [primitive-icons.md](references/primitive-icons.md). Browse the gallery at [`assets/icons.html`](assets/icons.html).
 - Terminal / CLI-window variant → [primitive-terminal.md](references/primitive-terminal.md)
 
 ### Background

package/framework/skills/effective-html/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: effective-html
+description: Create or redesign self-contained single-file HTML artifacts, including reports, explainers, landing pages, presentations, tools, wireframes, prototypes, plans, and diagrams. Route the request to the narrowest reference playbook, load only the guidance that applies, and verify the result at wide and narrow viewports. Do not use for ordinary application implementation when standalone HTML is not the deliverable.
+---
+
+# Effective HTML
+
+Build one self-contained HTML file that makes the subject clearer, easier to use, or easier to understand. This skill combines creative direction with specialized workflows for structure, fidelity, planning, and visual explanation. The standard is consistent care, not a consistent look.
+
+## Route the request first
+
+Read the brief and choose the narrowest playbook that owns the main review question:
+
+| Request | Reference |
+|---|---|
+| Palette, typography, composition, theming, or overall visual direction | [`design-artifact`](references/design-artifact.md) |
+| Unsettled information hierarchy, navigation, task flow, or responsive structure | [`html-wireframe`](references/html-wireframe.md) |
+| Polished mockup or working interactive flow | [`html-prototype`](references/html-prototype.md) |
+| Plan, roadmap, implementation sequence, or rollout document | [`html-plan`](references/html-plan.md) |
+| Relationships, sequence, topology, state, hierarchy, or quantitative structure | [`html-diagram`](references/html-diagram.md) |
+| Report, explainer, presentation, landing page, data story, or broad tool | Continue with this skill and load the applicable references below |
+
+The selected reference owns its specialist decisions. When a task spans domains, apply the relevant references in sequence and reconcile conflicts by user priority, project conventions, and the artifact's purpose. Do not load every reference by default.
+
+## Read the room before designing
+
+Inspect the user's request and supplied material. In a repository, look for `AGENTS.md`, `CLAUDE.md`, design-system documentation, tokens, existing components, and nearby artifacts.
+
+Authority runs in this order:
+
+1. The user's explicit visual and functional instructions.
+2. The project's established design system and conventions.
+3. The subject matter, audience, and purpose of the artifact.
+4. Your own design judgment.
+
+Before coding, settle the audience and job, form, visual register, fidelity, and useful interaction. Use real content and keep assumptions visible.
+
+## Load only the guidance the artifact needs
+
+- Reports, briefs, plans, explainers, and decks: [`documents-and-presentations`](references/documents-and-presentations.md)
+- Interfaces, calculators, and tools: [`interfaces`](references/interfaces.md)
+- Architecture, process, sequence, state, hierarchy, and concept diagrams: [`diagrams`](references/diagrams.md)
+- Quantitative charts, tables, metrics, and data stories: [`charts-and-data`](references/charts-and-data.md)
+- Visual direction when no project design system exists: [`creative-direction`](references/creative-direction.md)
+
+Read every reference that materially applies, then give the artifact one coherent direction.
+
+## Build contract
+
+- Produce one `.html` file with essential CSS and JavaScript inline. It must work when opened directly without a build step or external service unless the user permits one.
+- Use real content. Do not fill prominent space with placeholder copy, decorative statistics, or controls that do nothing.
+- Let content determine structure. Make sequences ordered, comparisons scannable, interfaces stateful, and diagrams legible.
+- Use semantic HTML, responsive layout, accessible contrast, visible keyboard focus, and reduced-motion handling.
+- Keep accidental horizontal overflow out of the page body. Put intentionally broad content in a contained scrolling or pannable region.
+- Define a small set of CSS tokens for the chosen direction and use them consistently.
+- Treat motion as explanation or feedback. Remove animation that adds no meaning or useful feedback.
+- Follow the user's or project's theme policy. When none exists, consider durable light and dark themes where they improve use.
+
+## Verify and hand off
+
+Write the file to the requested location, or choose a clear filename in the current workspace. When browser tooling is available, inspect wide and narrow viewports, exercise controls, check the console, and fix clipping, overlap, illegible text, broken states, and accidental overflow.
+
+Before delivery, check that the visual direction belongs to the subject rather than a generic neighboring topic. Return the absolute path and a short description of the artifact's visual and interaction choices, including important assumptions and deliberately omitted behavior.

package/framework/skills/effective-html/examples.md

@@ -0,0 +1,19 @@
+# Effective HTML Examples
+
+## Product workflow prototype
+
+User: "Create a self-contained HTML prototype for approving an expense report."
+
+Good behavior: Read `references/html-prototype.md` and `references/design-artifact.md`, choose the smallest credible approval flow, model loading, validation, success, failure, disabled, and mobile states, then verify keyboard interaction and responsive layout.
+
+## Architecture diagram
+
+User: "Show how the API, queue, worker, and database interact during order processing."
+
+Good behavior: Read `references/html-diagram.md` and `references/diagrams.md`, choose a sequence or topology model based on the reader's question, keep connectors and labels legible, and verify the diagram at wide and narrow widths.
+
+## Implementation rollout plan
+
+User: "Turn these migration notes into an HTML rollout plan."
+
+Good behavior: Read `references/html-plan.md` and `references/documents-and-presentations.md`, preserve commitments and terminology, separate decisions from assumptions and open questions, and verify that ownership, dependencies, and ordering remain visible.

package/framework/skills/effective-html/references/charts-and-data.md

@@ -0,0 +1,32 @@
+# Charts and data
+
+Read this when the artifact contains quantitative charts, metrics, tables, or a data-driven story.
+
+Start with the comparison the viewer needs to make. Select the chart from that question rather than from visual novelty:
+
+- Change over time → line, area, or aligned small multiples.
+- Ranked magnitude → ordered bars or a table with visual emphasis.
+- Part to whole → stacked bars when the denominator is meaningful; avoid decorative slices.
+- Distribution → histogram, dot plot, box plot, or density view.
+- Relationship → scatter plot with meaningful scales and annotations.
+- Flow → Sankey or network only when path magnitude is genuinely the point.
+
+Use a table when exact values matter more than shape. A chart and a compact table can coexist when they serve different reading needs.
+
+## Make the data honest
+
+- Label units, time ranges, sources, and important filters.
+- Use scales that support the intended comparison. Make truncation or nonlinearity explicit.
+- Separate measured values, estimates, targets, and forecasts visually and in text.
+- Do not invent data to make the artifact look complete. Mark missing or illustrative values plainly.
+- Keep color categories consistent and distinguishable without relying on color alone.
+- Treat status colors separately from the general palette.
+- Give dense data room; contain horizontal overflow rather than compressing labels into illegibility.
+
+## Interaction
+
+Tooltips should add precision, not carry facts that the chart otherwise fails to communicate. Keep essential values and conclusions available without hover.
+
+Filters, brushing, zooming, and linked views should answer real follow-up questions. Show active filters and provide a clear reset. Preserve an accessible summary or table for data that is otherwise available only through pointer interaction.
+
+Use animation to explain change between states, not to make bars and lines perform on arrival.

package/framework/skills/effective-html/references/creative-direction.md

@@ -0,0 +1,48 @@
+# Creative direction
+
+Read this when the user or project has not already supplied a complete visual direction.
+
+Operate like a small design studio with range, not a template engine with a favorite costume. Every artifact should feel designed for this commission. A planning memo, systems map, product demo, and launch deck can all show equal care without sharing a palette, typeface, silhouette, or amount of drama.
+
+## Find the direction inside the brief
+
+Start with the subject's own world: its materials, tools, environments, notation, history, audience, and language. Pull one organizing idea from there. It might shape the grid, the behavior of a diagram, the rhythm of the type, the way information reveals itself, or the role of imagery.
+
+Choose a register that fits:
+
+- **Workmanlike:** quiet hierarchy, exact spacing, restrained color, direct language. Right for plans, internal briefs, operational reports, and many tools.
+- **Editorial:** stronger composition, distinctive type, art-directed pacing, and one memorable visual move. Right for explainers, launches, research stories, and presentations that need to travel.
+- **Expressive:** a more immersive visual or interactive idea whose execution is itself part of the message. Use rarely, when the subject truly benefits.
+
+Do not confuse restraint with neglect or expression with a theatrical hero. Finish the chosen register properly.
+
+## Make a short design plan
+
+Before writing CSS, decide:
+
+- The visual premise in one sentence.
+- The hierarchy and organizing layout.
+- The color roles and why they belong to the subject.
+- The type roles and the voice each contributes.
+- The density, edge treatment, and image or diagram language.
+- The one place, if any, where motion or interaction carries meaning.
+
+The number of colors, typefaces, columns, and components should follow the idea. Do not satisfy a quota.
+
+## Avoid the template reflex
+
+Common components are not a visual direction. Cards, pills, rounded rectangles, gradients, tiny uppercase labels, large numerals, and side rails may be useful, but each must express real structure. Do not use them merely because they make an unfinished page look designed.
+
+Vary more than color. A new palette on the same centered hero and card grid is still the same design. Reconsider composition, scale, density, typography, shape language, navigation, and interaction.
+
+Use one decisive move rather than many unrelated flourishes. Let the rest of the page support it.
+
+Typography should establish voice and hierarchy. One well-used family can outperform an arbitrary pairing; several roles are useful only when they remain coherent. Use system fonts when they suit the brief. Embed custom fonts only when their value justifies the file weight and their license permits it.
+
+Color should be selected rather than inherited from habit. Neutrals are part of the palette. Status colors must remain semantically distinct from the decorative accent.
+
+## Respect prior art
+
+When the user names a style or supplies a reference, follow it faithfully, even if it resembles a convention you would not choose yourself. When a project has tokens and components, use them before inventing replacements.
+
+Bundled guidance is for technique, not imitation. Never copy a previous artifact's palette, typography, or composition simply because it worked once.

package/framework/skills/effective-html/references/design-artifact.md

@@ -0,0 +1,78 @@
+Take the perspective of the creative director at a boutique agency with a reputation for range — every commission gets its own visual identity, scaled to whatever level of treatment the brief actually merits. Palette, type, and layout should all be conscious decisions rooted in this particular subject; nothing should smell like it came off a shelf.
+
+## Begin by sizing up the brief
+
+The question is never *whether* to design — it's what register to design in. A memo deserves craftsmanship equal to a landing page; the two simply wear that craftsmanship differently.
+
+Much of what comes in wants a workmanlike register: plans, briefs, demos. Finish it properly — real hierarchy in the type, spacing that was thought about, a palette that was chosen — but know when to stop. Hardly any page benefits from a towering, theatrical hero. Ornament sparingly and with taste.
+
+Then there's work that earns the editorial register: landing pages, games, apps and tools someone will hold onto or pass along.
+
+When in doubt, remember that nobody ever regretted a well-composed page, whereas an identity pushed too hard sometimes backfires.
+
+Everything in the fundamentals section applies universally. The editorial process at the end only kicks in when your read of the brief calls for it.
+
+## Fundamentals for every artifact
+
+**Defer to prior art.** Before anything else, hunt for an established design system — a AGENTS.md or CLAUDE.md and/or DESIGN.md, QUALITY.md, PRODUCT.md etc, a tokens or theme file, styling on existing components. Found one? Apply it. The guidance below exists to plug holes, never to overrule. Authority flows in one fixed direction: what the user literally said, then whatever system the project already has, then your own taste.
+
+**Anchor everything to the subject.** Where the subject is fuzzy, sharpen it first: one concrete thing, a defined audience, a single purpose the page exists to serve. The most distinctive moves are excavated from the subject's native territory — the stuff it's made of, the tools of its trade, the language its people speak. Populate the build with genuine content from the first draft onward; lorem ipsum is banned.
+
+**Put two typefaces in conversation.** Even on a page that has nothing to do with letterforms, the letterforms do the heavy lifting. Never link webfonts from Google Fonts or any other font CDN — embed the face as a @font-face data URI instead. Cap measure at about 65 characters; commit to a type scale and don't wander off it; balance headings with `text-wrap: balance`, give paragraphs air, and space out uppercase labels with a hint of letter-spacing.
+
+**Neutrals are choices too.** A dead-center mid-grey announces that nobody thought about it; tint that grey faintly toward the accent and suddenly it reads as considered. There's nothing wrong with pure white or near-black grounds when the subject wants them — the test is whether the neutral was selected or merely left over.
+
+**Both themes, equal care.** Whatever theme the viewer runs is the theme your page renders in: the OS preference arrives via `prefers-color-scheme`, while the in-app toggle writes `data-theme="dark"` / `data-theme="light"` onto the root element — and the attribute must beat the media query going both ways. The sturdy pattern operates on tokens: declare the palette as custom properties on `:root`; inside `@media (prefers-color-scheme: dark)`, reassign only those tokens — components consume tokens exclusively and are never styled inside the media query itself — and then reassign the tokens a second time under `:root[data-theme="dark"]` and `:root[data-theme="light"]`. The dark counterpart deserves as much attention as the light original: mechanical inversion won't do; legibility and a working accent have to survive on either ground. A concept married to one visual world (the glow of an arcade cabinet, a letterpress invitation) is allowed to remain single-theme — provided that's a verdict you reached, not a corner you forgot.
+
+**Spacing belongs to the layout, not the elements.** Sibling groups get flex or grid plus `gap`; scatter per-element margins around and they'll collapse or compound behind your back. Broad content — tables, code, diagrams — sits in its own container with `overflow-x: auto` so horizontal scrolling never leaks to the page body. Wherever numerals stack into columns, switch on `font-variant-numeric: tabular-nums`.
+
+**Dodge the telltale AI aesthetic.** Right now, machine output keeps landing on the same few costumes: warm cream (#F4F1EA) under a serif display with a terracotta accent; near-black punctuated by one shot of acid-green or vermilion; hairline broadsheet rules over cramped columns; a purple-to-blue gradient hero floating on white; Inter or Space Grotesk chosen for safety; emoji doing the job of section markers; universal center alignment; `rounded-lg` sprayed everywhere; rounded cards wearing an accent bar or rail. A direction the user has pinned down gets executed faithfully — their instructions trump everything, up to and including a request for one of these exact looks. Absent instructions, that freedom is yours; don't blow it on a cliché.
+
+**Engineer it soundly.** Overlapping elements, cascade collisions, fonts silently falling back — rendering bugs breed in the distance between source and screen, so stay vigilant. Non-void elements all get closed, attributes all get double quotes, keyboard focus gets a visible state, and `prefers-reduced-motion` gets respected. When graphics turn generative or decorative, reach for Canvas or WebGL before hand-authoring long SVG path data.
+
+**Mind the cascade.** Selector specificity is where CSS goes to fight itself: a class hook like `.section` and an element hook like `.cta` can end up in a tug-of-war over padding and margins, each undoing the other. Architect the cascade so your spacing can't be quietly sabotaged.
+
+**Copy is a material.** Treat the words as load-bearing, not garnish. Stand on the reader's side of the glass: name things as people know them, not as the backend does (someone manages *notifications*, never *webhook config*). Verbs stay active; every control declares its exact effect ("Publish", answered by a toast: "Published"). An error message diagnoses the failure and prescribes the fix — never groveling, never hand-waving. Precision outperforms wit.
+
+**Make structure mean something.** Numbering, eyebrows, dividers, labels — these devices earn their place by asserting something true about the content, not by decorating it. Numbered markers (01 / 02 / 03) show up in generic work constantly, yet they're only honest when order is real information — an actual procedure, a dated timeline the reader must follow in sequence. Before deploying a device like that, ask whether it's telling the truth.
+
+**Interfaces are not documents.** A dashboard or tool is something people scan and drive, not something they read top to bottom, which relocates the craft from typography into information design. Lead with the rollup, follow with the detail; let form carry state alongside the figures — pills, chips, a severity stripe — so trouble is legible in a glance. Status colors (good / warning / critical) live in their own lane, apart from the accent hue, and can't be counted as it. Charts and sparklines get typographic-grade attention: an area fill, a whisper of grid, the endpoint emphasized. If it can be clicked, it should look clickable.
+
+## Process
+
+Code comes second. First, rough out a short design plan — a tight token system spanning color, type, and layout:
+- **Color**: 4–6 hex values, each with a name.
+- **Type**: faces covering 2+ roles — a display face with character, deployed with restraint; a body face that partners it; a utility face for captions or data if the work needs one.
+- **Layout**: the organizing idea, captured in a sentence or two.
+
+Build only after that, executing the plan and tracing every color and type decision back to it.
+
+## When the request is editorial
+
+Now the posture shifts: picture a client who has already thrown out every proposal that felt canned and is paying specifically for conviction. Commit to opinions, and place one honest aesthetic bet where the work will benefit.
+
+Audit the design plan against the subject before a line of code exists: any element that could pass for the stock answer to any similar brief gets reworked, with a note on what moved and the reasoning. The code gets written only after the plan has cleared that originality check — and then it follows the revised plan to the letter.
+
+**Principles**
+
+- Treat the hero as an argument: open on the single most characteristic artifact of the subject's world — headline, image, live demo, interactive moment.
+- The page's personality lives in its type. Choose the display/body pairing on purpose — not the families you'd reach for on autopilot — and lock in a scale with weights, widths, and spacing that were each decided. The treatment of the type should itself be one of the memorable things about the design, never a transparent vessel.
+- Motion is a budget to allocate. Ask where animation genuinely serves the subject — an entrance sequence on load, a reveal tied to scroll, micro-interactions on hover, a layer of ambient atmosphere — and whether it serves at all. A single orchestrated beat tends to outperform effects sprinkled around; let the direction decide. Bear in mind that restraint often wins, and gratuitous animation is itself a hallmark of the AI-generated look.
+- Scale the execution to the ambition. Maximalism demands elaborate follow-through; minimalism demands exactness in spacing, type, and detail. Elegance means delivering the chosen vision completely.
+- Concentrate the daring in one location and hush everything around it. Should the accent quarrel with the ground, slide it toward an analogous hue or drain some saturation — don't trade it for another color.
+
+## After the artifact ships
+
+Once the artifact is finished and delivered, ask the user whether they'd like to share it as a public page. If — and only if — they say yes, publish the file with the `tot` CLI (tot.page) and hand back the URL it prints:
+
+```bash
+tot path/to/artifact.html
+```
+
+If `tot` is not installed (`command -v tot` fails), tell the user and offer to install it. Install only on their explicit go-ahead:
+
+```bash
+npm install -g @plannotator/tot
+```
+
+Never publish or install without the user's explicit consent — a shared page is publicly accessible to anyone who has the link.

package/framework/skills/effective-html/references/diagrams.md

@@ -0,0 +1,68 @@
+# Diagrams, architecture, and sequences
+
+Read this when relationships, flow, time, state, or structure are the main thing the artifact must explain.
+
+## Choose the diagram before choosing the renderer
+
+Name the question the viewer should be able to answer, then choose the visual grammar:
+
+| Question | Useful grammar |
+| --- | --- |
+| What exists, and how is it connected? | Topology or system map |
+| What happens over time? | Sequence, timeline, or request trace |
+| What decisions or transformations occur? | Process flow |
+| How can something change? | State diagram |
+| What contains or owns what? | Hierarchy or nested boundary map |
+| How do alternatives compare? | Matrix or aligned comparison |
+| How much, how often, or how fast? | Quantitative chart; also read [`charts-and-data.md`](charts-and-data.md) |
+
+Do not force several questions into one overloaded picture. Use coordinated views or selectable layers when the audience genuinely needs more than one.
+
+## Choose the medium from the information
+
+- **HTML and CSS:** strong for labeled regions, aligned comparisons, grids, timelines, and diagrams whose text needs to reflow.
+- **SVG:** strong for crisp relational diagrams, custom paths, annotations, and interactive vector scenes.
+- **Canvas:** strong for dense, frequently changing, or generative graphics where thousands of DOM nodes would be wasteful.
+- **WebGL:** reserve for spatial, high-volume, or truly three-dimensional work that earns the added complexity.
+
+Mix media when useful. A diagram can use semantic HTML controls and explanation around an SVG or Canvas stage.
+Style SVG elements through CSS classes and the artifact's chosen tokens when practical so the scene remains coherent across states and themes.
+
+## Make the structure legible
+
+- Establish hierarchy with position, grouping, containment, scale, and whitespace before reaching for color.
+- Keep labels readable at the default view. Do not rotate important prose or place text over busy paths.
+- Route connectors around nodes and labels. Make direction unmistakable and distinguish different edge meanings.
+- Use boundaries to communicate ownership, trust, deployment, or responsibility, not as decoration.
+- Keep a stable overview while exposing detail on demand.
+- For architecture, show the concepts the audience uses. File names and implementation classes belong only when the question is specifically about code structure.
+
+Avoid the automatic architecture wallpaper of identical rounded boxes connected by arrows. Services, queues, actors, boundaries, stores, and transformations do not all need the same shape or visual weight.
+
+## Sequence and interaction
+
+Sequence should expose causality, not merely flash elements in order.
+
+- Give steps durable labels and a visible current state.
+- Let the viewer play, pause, restart, step, or choose a path when the sequence is more than a brief self-explanatory animation.
+- Keep the full system understandable when animation is stopped.
+- Use motion to trace requests, reveal transitions, or connect cause with effect. Respect `prefers-reduced-motion` with an immediate or step-based alternative.
+- Use filtering and layer toggles when they reduce complexity without hiding necessary context.
+
+If nodes expose details, make selection obvious. Floating panels must be dismissible and must reopen from the relevant node or control. Important information must remain reachable by keyboard.
+
+## Pan and zoom only when needed
+
+A clear diagram that fits should not become a map application. Add pan and zoom when the information space materially exceeds the viewport or close inspection is part of the task.
+
+For an SVG stage:
+
+- Transform one containing `<g>` rather than rewriting every node.
+- Keep pointer, pan, and zoom math in a single coordinate system. Preserve the point under the cursor while zooming.
+- Suppress click activation after a drag using a small movement threshold.
+- Provide `grab` and `grabbing` feedback, a visible zoom level, and a reset control.
+- Set useful minimum and maximum scales and ensure the initial fit is understandable.
+
+## Verify the picture
+
+Inspect the default overview, every interactive state, and any sequence endpoints. Check that connectors do not cross labels, arrows terminate cleanly, text remains legible, panels do not cover critical content, and narrow-screen behavior has an intentional fallback.

package/framework/skills/effective-html/references/documents-and-presentations.md

@@ -0,0 +1,28 @@
+# Documents and presentations
+
+Read this for reports, briefs, plans, explainers, comparisons, and slide-like artifacts.
+
+## Documents
+
+Design around the reader's decision or understanding, not around a generic page outline. The opening should orient quickly: what this is, why it matters, and what deserves attention. Follow with evidence, structure, and detail in the order the reader needs them.
+
+- Keep prose measures readable and let tables, timelines, code, and diagrams use wider regions.
+- Use headings, labels, numbering, dividers, and callouts only when they express genuine hierarchy or sequence.
+- For plans, stay close to the user's language and ambition. Clarify ownership, order, dependencies, risks, and completion conditions without inventing a larger program.
+- For reports, distinguish observation, interpretation, recommendation, and uncertainty.
+- For comparisons, keep like-for-like attributes aligned so the eye can compare without remembering.
+- For print-oriented work, add sensible print styles and avoid interactions that hide essential content.
+
+Most operational documents want a workmanlike register. They still deserve intentional typography, spacing, and color, but rarely need a giant hero or ornamental dashboard furniture.
+
+## Presentations
+
+A presentation is paced, not merely paginated. Give each screen one job and one dominant idea.
+
+- Establish a visual rhythm across slides, then break it only for emphasis.
+- Keep essential information visible without hover.
+- If the file behaves like a deck, support keyboard navigation, clear progress, and direct slide links when practical.
+- Use builds and transitions to control explanation order, not to decorate every change.
+- Ensure a useful narrow-screen or scrolling fallback when the fixed stage cannot fit.
+
+When a request blends a document and a deck, prefer the reading mode the audience will actually use rather than building two half-working experiences.

package/framework/skills/effective-html/references/html-diagram.md

@@ -0,0 +1,43 @@
+# HTML Diagram
+
+Build the smallest visual model that makes the relationship easier to understand than prose alone. Match the notation and visual language to the user's project and subject. Do not force every topic into the same SVG boxes and arrows.
+
+## Choose the right model
+
+Identify the question the reader should answer, then select the form:
+
+- topology for components and connections;
+- sequence for ordered messages over time;
+- process for steps, branches, and handoffs;
+- state for transitions and conditions;
+- hierarchy for containment or ownership;
+- timeline for change over time;
+- matrix for repeated relationships;
+- quantitative view when magnitude matters.
+
+Decide what must remain visible together and what can be revealed on demand. Use a simpler form when it carries the same meaning.
+
+## Choose the rendering method
+
+Use HTML and CSS, SVG, Canvas, or WebGL according to the information and scale. Do not use SVG merely because the output is a diagram.
+
+- Keep labels, grouping, direction, and connectors legible before adding interaction.
+- Use stable node positions when readers must compare states or steps.
+- Keep edge crossings and ambiguous arrowheads to a minimum.
+- Put intentionally broad canvases in a contained pan or scroll region.
+- Use legends only when notation is not self-explanatory.
+
+Add sequencing, filtering, path tracing, pan and zoom, or animation only when it helps answer the stated question. Keep overlays dismissible, controls keyboard-accessible, and motion compatible with `prefers-reduced-motion`.
+
+When [`design-artifact`](design-artifact.md) is available, read it for
+the diagram's surrounding composition and visual register. Keep the chosen
+diagram grammar, label legibility, and relationships authoritative over
+decorative treatment.
+
+## Build and verify
+
+Deliver one self-contained HTML file with essential CSS and JavaScript inline. Require no build step or external service. Use accessible text alternatives and keep important meaning available without animation or color alone.
+
+Inspect the result at wide and narrow widths. Check label collisions, clipped nodes, edge routing, reading order, keyboard operation, overflow, and every interactive state.
+
+Return the absolute path, the diagram form chosen, and the main simplifications or assumptions.

package/framework/skills/effective-html/references/html-plan.md

@@ -0,0 +1,40 @@
+# HTML Plan
+
+Turn source material into a plan people can inspect and act on. Preserve the user's scope, ordering, commitments, and terminology unless they ask for broader synthesis.
+
+## Shape the document around the work
+
+Read the conversation, project instructions, and supplied plan before designing. Match an existing design language when one is present. Otherwise derive a quiet, workmanlike direction from the audience and subject.
+
+When [`design-artifact`](design-artifact.md) is available, read its
+fundamentals to make that direction intentional. Keep this skill's traceability
+and source-preservation rules authoritative; creative direction must not
+inflate the plan into a dashboard or campaign page.
+
+Decide what the plan actually needs:
+
+- phases or sequence;
+- status and decision points;
+- owners and collaborators;
+- dependencies and risks;
+- acceptance checks;
+- unresolved questions.
+
+Do not add a timeline, progress percentage, status badge, or dashboard summary unless the source supports it. Improve grammar and structure without inflating an implementation plan into a strategy document.
+
+## Preserve traceability
+
+- Keep source commitments recognizable.
+- Separate accepted decisions from assumptions and open questions.
+- Show sequence and dependency only where they are real.
+- Use tables for exact mappings, comparisons, or repeated fields.
+- Use a flow or timeline only when it makes order materially easier to understand.
+- Keep long prose readable instead of forcing every paragraph into a card.
+
+## Build and verify
+
+Deliver one responsive, accessible, self-contained HTML file. Use semantic headings, lists, tables, and landmarks. Keep essential CSS and JavaScript inline, avoid external services, and make any navigation or disclosure keyboard-operable.
+
+Inspect the result at wide and narrow widths. Check that no commitment disappeared, that stages remain in the intended order, that ownership and dependencies are legible, and that long content does not overflow.
+
+Return the absolute path and note any structural interpretation you introduced.