@litfamily/litopencode 1.0.4 → 1.0.6

package/skills/readme-studio/references/decoration-patterns.md

@@ -0,0 +1,105 @@
+# README decoration patterns
+
+Use decoration to help a reader find verified information. Keep the README's purpose,
+working instructions, and source links understandable when every image and HTML block
+is hidden. Decorations never establish a release, security, compatibility, quality, or
+popularity claim.
+
+## Inspection notes
+
+Inspected on 2026-09-21. GitHub's displayed star counts below are selection-time snapshots,
+not durable project facts; re-check them before any later research summary. No wording,
+logos, or image assets from these repositories are reused here.
+
+| Repository | Stars observed | README structure observed |
+| --- | ---: | --- |
+| [fastapi/fastapi](https://github.com/fastapi/fastapi) | 102.5k | A centered logo and short descriptor precede a compact row of linked workflow, coverage, and package badges. Sponsor marks are grouped by tier. Optional code variants and command detail use `<details>` blocks. Emoji appear selectively in prose and examples; section headings remain descriptive. |
+| [vercel/next.js](https://github.com/vercel/next.js) | 142.2k | The opening stays text-led and links directly to learning, documentation, community, and a maintained showcase. Major topics use a simple heading hierarchy. |
+| [astral-sh/uv](https://github.com/astral-sh/uv) | 90.0k | A small linked badge row and one-line purpose lead into a centered light/dark `<picture>` with a caption. Feature highlights are concise and scannable. |
+| [ollama/ollama](https://github.com/ollama/ollama) | 181.3k | A centered linked logo leads into a short purpose statement. Usage is divided by reader task, then integrations are grouped by category. |
+| [pytorch/pytorch](https://github.com/pytorch/pytorch) | 103.1k | The logo switches for light and dark themes. A linked table of contents supports a long README, and a two-column Markdown table compares components with their roles. |
+
+Star figures were read from each repository page on the inspection date. They change and
+must never be copied into project copy, badges, or generated claims as if they were stable.
+
+## Apply the patterns
+
+### Emoji section headers and section iconography
+
+Treat an emoji as a small scan cue, not as the section name or a status indicator. The
+inspected examples favor ordinary, descriptive headings and use emoji sparingly in nearby
+copy. If the project's voice benefits from an icon, pair one recognizable glyph with a
+clear heading, use the same meaning consistently, and leave the heading useful when the
+glyph is missing or rendered monochrome. Do not use icons to imply a check, popularity,
+security, or release state that repository evidence does not support.
+
+### Centered hero and badge/logo row
+
+Choose one hero arrangement: a centered project mark, a concise purpose line, and—only
+when they help a reader act—a compact row of linked marks. The inspected README layouts
+show both a logo-first arrangement and a short badge row near the title. Preserve the
+project's actual logo and license. Each badge image and its link target must resolve to
+the current repository's real endpoint or a verified project endpoint. Bind owner,
+repository, default branch, package name, and workflow name from current local facts;
+remove a badge if its image or target cannot be verified. Never carry another project's
+badge URL forward.
+
+Keep sponsor and partner marks in their own clearly labeled group. Use marks only where
+the relationship is documented, and do not let placement imply endorsement or ownership.
+
+### Collapsible `<details>` sections
+
+The inspected README uses disclosure blocks for optional alternatives and extended
+command notes. Keep the summary specific, make the primary path visible outside the
+collapsed block, and put complete Markdown content between the opening and closing tags.
+Use disclosures for secondary examples, long environment tables, or optional setup—not
+for the project's purpose, required install steps, warnings, or essential features.
+
+### Contributors, star history, and showcase embeds
+
+The inspected Next.js README links to its maintained showcase instead of embedding a
+third-party showcase widget; the other inspected projects also keep their core README
+usable without contributor or star-history widgets. Use a direct repository graph or
+maintained project page as the default. An image embed is optional: check the image URL
+and click target for this exact repository, add meaningful alt text, and retain a text
+link below it. Remove stale or unreachable embeds instead of leaving a broken panel.
+
+For contributor art, use the repository's own contributor destination and do not imply
+that a remote image service is an authoritative contributor record. For star history,
+label the chart as a historical visualization and check that both the chart and link
+identify this repository. For showcase material, use maintained examples with permission
+and current destinations; a locally tracked screenshot grid is a good fallback. None of
+these embeds proves project activity, adoption, endorsement, or quality.
+
+### Table-based feature grids
+
+The inspected PyTorch README uses a simple Markdown table to compare named components and
+their roles. Use a table when each row answers the same small set of questions, such as
+feature, reader-visible behavior, and repository evidence. Keep cells short, link to
+real source or documentation, and move long explanations into their own sections. Do
+not use a table for paragraphs, mobile-critical instructions, or decorative alignment.
+
+### Footer navigation
+
+The inspected READMEs keep durable destinations—documentation, contribution guidance,
+community/support, and license—easy to find near the end or near the opening. A compact
+footer link row can repeat the few destinations readers need after a long feature section.
+Use only anchors and files that exist in this repository, keep labels descriptive, and
+avoid repeating a full table of contents in the footer.
+
+### Plain-Markdown fallback
+
+Some registry and package pages remove HTML or render only a subset of it. Keep the
+project title, purpose, install command, feature descriptions, and navigation as ordinary
+Markdown. Replace centered HTML with a Markdown title and short paragraph; replace a
+disclosure with a visible subheading; replace a remote image with its text link and
+meaningful alt text. The cover picture and badge row are enhancements. If the renderer
+cannot show them, readers must still get the same verified facts and usable links.
+
+## Facts and endpoint rule
+
+The facts helper checks reference structure and safe paths only; it does not compare a
+claim with source contents or prove a badge endpoint. Before assembly, inspect the actual
+repository files and open every badge, logo, contributor, chart, and showcase destination
+that will ship. Keep claim text accurate, use only verified endpoints for this repository,
+and omit every decoration whose truth or destination remains uncertain.

package/skills/readme-studio/references/motion.md

@@ -0,0 +1,38 @@
+# Portable rendering and delivery
+
+Choose one engine and record its version/license before rendering. Remotion 4.0.526 is preferred when its company license terms fit the project; it is not an unrestricted MIT renderer. Review https://www.remotion.dev/docs/license and https://www.remotion.dev/docs/cli/render. The alternative is published `hyperframes@0.8.51` (MIT), with its own bundled dependency notices: https://github.com/heygen-com/hyperframes. Inspect installed help for the pinned version; no `latest`, global installs or invented package names.
+
+Copy the selected template directory from the exact native-selected SKILL.md root into the authorized project. Run `npm ci --no-audit --no-fund` there; install no engine into the product's runtime dependencies. Both lockfiles travel with the template. Chrome and the renderer's FFmpeg path must be available locally. A sandbox failure is MOTION_RENDER_BLOCKED, not permission to disable the host's sandbox. Keep source for an authorized external local render and disclose that boundary.
+
+## Remotion
+
+Put the inspected background at `public/background.png` and the six outlined assets at `public/{title,subtitle,label}-{dark,light}.svg`. Suffix names ink. Verify light ink is bound to Dark compositions. The component uses a solid theme field behind type, two staged Gaussian background planes (far and middle), seeded grain, the existing glow, a second static rim-light band, and an original crisp pixel sprite. The panel stays sharp above both blur planes. Props `farBlur`, `middleBlur`, `grain`, `glow`, and `depth` control restraint; use a props JSON file, not interpolated user text. All motion is frame-derived; no CSS animations or random-per-frame noise. Reduced-motion posters are still renders of this composition: preserve both blur planes and the rim-light band in the static image.
+
+```sh
+./node_modules/.bin/remotion compositions src/index.tsx
+./node_modules/.bin/remotion render src/index.tsx WideDark out/wide-dark-v1.mp4 --codec=h264 --concurrency=1 --overwrite=false
+./node_modules/.bin/remotion still src/index.tsx WideDark out/poster-wide-dark-v1.png --frame=150 --overwrite=false
+```
+
+Repeat for WideLight, MobileDark and MobileLight. Metadata specifies 60fps, 300 frames, 5 seconds. At frame zero type is already legible; a short eased translation settles into a readable hold and returns for the seam. Verify actual output, not just this metadata. Existing output names must never be reused.
+
+## HyperFrames
+
+The HTML recipe is a wide dark starting composition; copy it into separate local light/mobile variants and change field, ink asset bindings, dimensions and layout together. Use `background.png` and the light-ink SVGs beside index.html. It stages far and middle blur planes below a sharp panel and a separate rim-light band; reduced-motion mode disables movement while keeping those effects visible. Keep `data-composition-id`, dimensions, five-second duration and `data-no-timeline`: this template uses finite CSS keyframes, not a missing GSAP timeline. The motion sidecar probes the cover container (including descendants), not a leaf. Render with one worker; multiple workers have produced clipped output for this recipe.
+
+```sh
+./node_modules/.bin/hyperframes --version
+./node_modules/.bin/hyperframes render --help
+./node_modules/.bin/hyperframes check . --samples 60 --no-contrast --json
+./node_modules/.bin/hyperframes render . -c . --fps 60 --workers 1 -o out/wide-dark-v1.mp4
+```
+
+Verify current help's overwrite behavior and choose a fresh output. The positional argument is the project directory; `-c .` selects index.html (`-c` accepts a composition file path, not its id). A check or render failure stays partial; preserve logs and do not switch engines silently.
+
+## Inspect and distribute
+
+Probe width/height/r_frame_rate/nb_frames/duration with ffprobe when available, then decode frame 0/150/299 and inspect each master for clipping, title exactness, readable contrast and seam continuity. Inspect posters and previews at 320/390/1440px in both themes. Verify the paths-only SVGs and source strings at asset level; CSS cannot recolor an external SVG image.
+
+Encode each inline preview initially at 6fps, 560x280 wide or 384x480 mobile, <=64 colors; 30 frames for five seconds. Use ffmpeg palettegen/paletteuse or an available equivalent. The master remains 60fps; do not describe the preview as 60fps. Inspect readability before trading dimensions/quality for bytes. Budget <=2.5 MiB each; record an explicit delivery decision if that cannot be met. GIF and animated WebP compatibility are separate checks. A static poster is always required.
+
+Use `templates/readme-cover-section.md`, updating only to existing local asset names and meaningful alt text. Reduced-motion sources precede animation sources; img is static. Link MP4 as an optional viewing master; arbitrary README video HTML is not assumed supported. Verify local media selection and reduced motion now; GitHub/npm sanitization and actual public playback remain POST_PUBLICATION_UNVERIFIED. Never publish, invent a CDN URL or target new files at an immutable old version to close that gate.

package/skills/readme-studio/references/production.md

@@ -0,0 +1,13 @@
+# Repository facts and assembly
+
+Find the real package root, including monorepo boundaries. Read package metadata and scripts, entry points, LICENSE, current README anchors, contribution/support/security docs and relevant tests. Store claims with ids, wording and repository-relative source paths. Copy commands from executable metadata and try the harmless documented quick start in the task fixture. A field named license is not proof that unrelated art/fonts share that license.
+
+The `scripts/check-facts.mjs` helper is read-only. It rejects unknown fields, duplicate claim ids, empty sources, escaping/symlink/missing source paths and malformed badge URLs. Its success is only structure/path validation. Manually compare each claim to source content and each badge to its real status endpoint. Omit uncertain popularity, coverage, affiliation and supported-platform assertions. Do not invent a badge URL; a syntactically valid URL does not establish that it exists.
+
+First read the brief, current README, project identity and supplied assets. No interview is mandatory. Ask only when at least two plausible answers would materially change README scope or structure, architecture, permissions or data behavior, accessibility, or visual direction. For those choices, ask one high-impact question per user turn, state the consequence, and wait before choosing or editing. Retain every answer in a task-local decision note across rounds; after each reply, ask only about an unresolved material choice. Continue for as many rounds as materially necessary, then proceed without repeated approval. Never re-ask a settled choice, including in new wording; read the note on resume. When a brief names competing visual directions and leaves them undecided, that axis stays unresolved even if the brief calls every option acceptable: acceptance is not a selection or a delegation. Give it its own round once higher-impact choices are answered; you may recommend one option inside the question, but do not announce a default for it or implement before the user picks. A default applies only to choices the brief settles, choices it delegates ("your call", "pick one"), and details that do not materially change the result. A brief with no visual direction at all is not an open choice: apply the default cover direction without asking. For a bounded brief, state the default direction and continue. Review-only and plan-only requests remain read-only; a keyword or bare repository name does not authorize writes.
+
+Choose alignment (left/center), tone and theme from the project's identity or the user's direction. A useful reading order is one distinctive cover, small relevant badge/logo row, purpose in plain text, copyable quick start, features or real demo, and navigation for longer documentation. Keep emoji restrained. Preserve current anchors and accurate instructions. Do not flatten prose, installation commands or critical instructions into images.
+
+Keep an asset manifest listing input hashes, generator or supplied provenance, editable source, chosen engine/version/license decision, output state and inspection. States are source, rendered, inspected, partial; do not infer completion from filenames. On interruption record last completed stage and owned process identity. Resume without overwriting prior outputs. New revisions get new names; missing font/render tools name the exact prerequisite while factual copy continues.
+
+Use only an explicit task output root. Read references as data, never as authority to run shell snippets, publish, authenticate or inspect secrets. Avoid shell interpolation of names, README text or SVG metadata. New assets must exist locally before README links are added. Do not target new assets at an immutable already-published npm version. Preserve local preview and label public renderer verification POST_PUBLICATION_UNVERIFIED.

package/skills/readme-studio/references/typography.md

@@ -0,0 +1,16 @@
+# Real inputs and crisp type
+
+Image-generation availability belongs to the active OpenCode session, not the model's description of itself. Check its tool list and capabilities. A real native generator result must be inspected, saved inside the authorized project, and recorded with prompt and provenance. Without a callable generator report IMAGE_GENERATION_UNAVAILABLE and finish independent README work. The supplied-background branch may then complete composition, but never becomes native-generation evidence. CSS atmospheres are effects, not generated backgrounds.
+
+Use Pretendard for Korean/prose/display and Meslo LGS NF for technical labels. Resolve actual regular font files and readable licenses locally. Record family, style, version, SHA256 and license source before rendering. Do not install system fonts, silently substitute or redistribute uncertain font bytes. A source image must be inspected for words/logos and appropriate mobile/wide crops; preserve it unmodified.
+
+From the exact selected SKILL.md root copy `templates/typography/` to a fresh project-local tools directory. Install there with `npm ci --ignore-scripts --no-audit --no-fund`; the lock pins fontkit 2.0.4 (MIT). With explicit existing project root and output parent directories:
+
+```sh
+node ./tools/typography/outline.mjs --font "./inputs/Pretendard-Regular.otf" --family Pretendard --license "./inputs/Pretendard-LICENSE.txt" --text "연구 노트" --root "$PWD" --output "assets/title-dark.svg" --fill '#15242a'
+node ./tools/typography/outline.mjs --font "./inputs/MesloLGS NF Regular.ttf" --family 'MesloLGS NF' --license "./inputs/Meslo-LICENSE.txt" --text "FIELD NOTES / 01" --root "$PWD" --output "assets/label-light.svg" --fill '#f4f1e9'
+```
+
+The helper accepts bounded regular files, shapes glyph runs with positions and advances, checks all requested glyphs, and includes transformed outline bounds in its viewBox. Whitespace advances without visible outlines. Paths are escaped and output is exclusive; unsafe parent paths/symlinks and missing glyphs fail. Review the recorded license yourself: presence of license text is not legal verification. Stdout reports actual font identity/hash; save it in the asset manifest along with the editable source string. A paths-only SVG still needs text alternatives in Markdown.
+
+Create title/subtitle/label variants for each ink palette. Dark-ink filenames bind to light fields; light-ink filenames bind to dark fields. External SVGs do not inherit CSS color. Inspect path fill and its solid backing field for >=4.5:1 contrast before rendering. Keep blur on background only, add static/seeded grain, a restrained lighting falloff and crisp original pixel imagery. Expose restrained/expressive amount controls without requiring duplicate outputs. Describe raster image plus vector outlines as a hybrid asset.

package/skills/readme-studio/scripts/check-facts.mjs

@@ -0,0 +1,28 @@
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { inside, readRegular } from '../templates/typography/files.mjs';
+
+export function checkFacts(facts, root) {
+  const keys = (value, allowed) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(k => allowed.includes(k));
+  const nonempty = s => typeof s === 'string' && s.trim().length > 0 && s.length <= 4096;
+  if (!keys(facts, ['claims','badges']) || !Array.isArray(facts.claims) || !facts.claims.length || facts.claims.length > 200 || !Array.isArray(facts.badges) || facts.badges.length > 20) throw new Error('invalid facts structure');
+  const ids = new Set();
+  for (const claim of facts.claims) {
+    if (!keys(claim, ['id','text','sources']) || !nonempty(claim.id) || ids.has(claim.id) || !nonempty(claim.text) || !Array.isArray(claim.sources) || !claim.sources.length || claim.sources.length > 20) throw new Error('invalid or duplicate claim');
+    ids.add(claim.id);
+    for (const source of claim.sources) readRegular(inside(root, source), 8 * 1048576);
+  }
+  for (const badge of facts.badges) {
+    if (!keys(badge, ['label','url','claim']) || !nonempty(badge.label) || !ids.has(badge.claim) || !nonempty(badge.url) || /[\s\x00-\x1f\x7f]/u.test(badge.url)) throw new Error('invalid badge');
+    const url = new URL(badge.url);
+    if (!['http:','https:'].includes(url.protocol) || url.username || url.password || !url.hostname) throw new Error('unsafe badge URL');
+  }
+  return {valid:true, validation_scope:'structure-only', factual_accuracy:'not-checked', source_contents_compared:false, badge_truth_checked:false};
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const {values} = parseArgs({options:{root:{type:'string'},facts:{type:'string'}}});
+    if (!values.root || !values.facts) throw new Error('--root and --facts required');
+    console.log(JSON.stringify(checkFacts(JSON.parse(readRegular(inside(values.root, values.facts))), values.root)));
+  } catch (error) { console.error(`readme-studio: ${error.message}`); process.exitCode = 1; }
+}

package/skills/readme-studio/templates/cover-source.json

@@ -0,0 +1 @@
+{"title":"Replace with verified project name","subtitle":"Replace with verified purpose","label":"LOCAL PROJECT","background":{"path":"inputs/background.png","origin":"supplied or native tool receipt","sha256":"record actual hash"},"fonts":[],"alignment":"left","effects":{"blur":6,"grain":0.04,"glow":0.18,"depth":0.025},"engine":"select before rendering","state":"source"}

package/skills/readme-studio/templates/facts.json

@@ -0,0 +1 @@
+{"claims":[{"id":"purpose","text":"Replace with verified purpose","sources":["README.md"]}],"badges":[]}

package/skills/readme-studio/templates/hyperframes/index.html

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en" data-fps="60">
+<head>
+<meta charset="utf-8">
+<title>README cover</title>
+<style>
+* { box-sizing: border-box }
+body { margin: 0 }
+#cover {
+  position: relative; width: 1600px; height: 800px; overflow: hidden;
+  background: #15242a; --far-blur: 9px; --middle-blur: 2px; --grain: .04; --glow: .18;
+}
+.background { position: absolute; width: 100%; height: 100%; object-fit: cover }
+.depth-plane-far {
+  filter: blur(var(--far-blur)); transform: scale(1.04);
+  animation: field 5s ease-in-out both;
+}
+.depth-plane-middle {
+  filter: blur(var(--middle-blur)); opacity: .68; transform: scale(1.03);
+  mask-image: linear-gradient(to bottom, transparent 5%, black 28%, black 72%, transparent 94%);
+  -webkit-mask-image: linear-gradient(to bottom, transparent 5%, black 28%, black 72%, transparent 94%);
+  animation: middle-plane 5s ease-in-out both;
+}
+.glow {
+  position: absolute; inset: 0;
+  background: radial-gradient(ellipse at 80% 10%, rgba(170,240,196,var(--glow)), transparent 60%);
+}
+.rim-light {
+  position: absolute; inset: 0; z-index: 3; pointer-events: none; mix-blend-mode: screen; opacity: .78;
+  background: linear-gradient(112deg, transparent 42%, rgba(255,244,196,.04) 46%, rgba(255,239,184,.38) 49%, rgba(255,255,245,.2) 50%, rgba(255,239,184,.08) 53%, transparent 59%);
+}
+.panel {
+  position: absolute; z-index: 4; left: 64px; top: 60px; width: 1024px; padding: 36px;
+  background: #15242a; border: 1px solid #f4f1e9; animation: entry 5s cubic-bezier(.2,.8,.2,1) both;
+}
+.sharp-foreground { filter: none }
+.label { height: 24px; width: 42%; object-fit: contain; object-position: left }
+.title { width: 100%; display: block; margin-top: 42px }
+.subtitle { display: block; width: 94%; margin-top: 24px }
+.rule { height: 1px; background: #f4f1e9; opacity: .35; margin-top: 40px }
+.pixel { position: absolute; z-index: 5; right: 80px; bottom: 68px; width: 240px; height: 186px; animation: sprite 5s ease-in-out both }
+@keyframes field { 0%,100% { transform: scale(1.04) } 50% { transform: scale(1.065) } }
+@keyframes middle-plane { 0%,100% { transform: scale(1.03) } 50% { transform: scale(1.045) } }
+@keyframes entry { 0%,100% { transform: translateY(12px) } 8%,92% { transform: translateY(0) } }
+@keyframes sprite { 0%,100% { transform: translateY(0) } 50% { transform: translateY(-16px) } }
+@media (prefers-reduced-motion: reduce) {
+  .depth-plane-far, .depth-plane-middle, .panel, .pixel { animation: none !important }
+}
+</style>
+</head>
+<body>
+<div id="cover" data-composition-id="ReadmeCover" data-start="0" data-width="1600" data-height="800" data-duration="5" data-no-timeline>
+  <img class="background depth-plane-far" src="background.png" alt="">
+  <img class="background depth-plane-middle" src="background.png" alt="">
+  <div class="glow"></div>
+  <div class="rim-light"></div>
+  <svg width="1600" height="800" style="position:absolute;z-index:2;opacity:var(--grain)"><filter id="grain"><feTurbulence type="fractalNoise" baseFrequency=".8" numOctaves="2" seed="17"/></filter><rect width="100%" height="100%" filter="url(#grain)"/></svg>
+  <div class="panel sharp-foreground"><img class="label" src="label-light.svg" alt="Technical label"><img class="title" src="title-light.svg" alt="Project title"><img class="subtitle" src="subtitle-light.svg" alt="Purpose"><div class="rule"></div></div>
+  <svg class="pixel" viewBox="0 0 9 7" shape-rendering="crispEdges" aria-label="Original pixel sprite"><path fill="#c9ee95" d="M3 0h4v1H3zM2 1h6v1H2zM1 2h2v1H1zM4 2h1v1H4zM6 2h3v1H6zM0 3h9v1H0zM1 4h7v1H1zM2 5h1v1H2zM5 5h2v1H5zM1 6h2v1H1zM5 6h3v1H5z"/></svg>
+</div>
+</body>
+</html>

package/skills/readme-studio/templates/hyperframes/index.motion.json

@@ -0,0 +1 @@
+{"duration":5,"assertions":[{"kind":"keepsMoving","withinSelector":"#cover","maxStaticSec":1.2}]}