init

Author: elkaix

.agents/skills/gen-changesets/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: gen-changesets
+description: Use when generating changesets in the pythinker-code repository, including package bump selection, internal package and CLI bundle handling, bump levels, major confirmation, and English changelog wording.
+---
+
+# Generate Changesets
+
+`pythinker-code` uses changesets to manage versions and changelogs. The current user-facing published package is:
+
+- `@pythoughts/pythinker-code`: the CLI
+
+All other `@pythoughts/*` packages are treated as internal packages, including `@pythoughts/pythinker-code-sdk`, `agent-core`, `kosong`, `kaos`, `pythinker-code-oauth`, `pythinker-telemetry`, and `migration-legacy`.
+
+## Core Rules
+
+1. **Inspect the actual changes first.** Use `git status` / `git diff --name-only` to identify which packages were actually changed.
+2. **List packages that changesets can release.** If a changed package is ignored in `.changeset/config.json`, do not put that ignored package in frontmatter together with a non-ignored package; changesets rejects mixed ignored/non-ignored frontmatter.
+3. **Map ignored internal changes to the affected released package.** If an ignored internal package changes CLI output or behavior, list `@pythoughts/pythinker-code` and describe the actual user-visible or release-artifact change in the changelog text.
+4. **Internal package source changes that enter the CLI bundle must manually list the CLI.** `@pythoughts/pythinker-code` inline-bundles `@pythoughts/*` source, but those internal packages are devDependencies from the CLI's perspective, so changesets will not automatically propagate bumps. If a change enters the CLI output, list `@pythoughts/pythinker-code`.
+   - **Web app (`@pythoughts/pythinker-web`) changes always enter the CLI bundle.** `@pythoughts/pythinker-web` is ignored by changesets (see `.changeset/config.json`) and cannot be mixed with `@pythoughts/pythinker-code` in one changeset frontmatter. Describe the web change in the changelog text, but list `@pythoughts/pythinker-code` so the CLI release carries the bundled `dist-web` output.
+5. **Docs-only and tests-only changes usually do not need a changeset.** README, internal docs, and `test/` changes that do not enter package output do not trigger a CLI bump.
+6. `@pythoughts/dashboard` / `dashboard-server` / `dashboard-web` are ignored by changesets and should not be handled.
+
+## Workflow
+
+1. List the changed packages and check whether each one is ignored by `.changeset/config.json`.
+2. Choose a bump level for each package.
+3. If an ignored internal package change enters the CLI bundle, put `@pythoughts/pythinker-code` in frontmatter instead of mixing the ignored package into the same changeset.
+4. Create a short kebab-case file under `.changeset/`.
+5. Split unrelated changes into separate changesets; keep one logical change in one file.
+
+Format:
+
+```markdown
+---
+"<package A>": patch
+"<package B>": minor
+---
+
+<English changelog entry>
+```
+
+## Bump Levels
+
+| Level | When to use |
+|---|---|
+| `patch` | Bug fixes; build/package fixes; internal refactors that do not change behavior; wording tweaks; small dependency upgrades |
+| `minor` | New backwards-compatible features or capabilities |
+| `major` | Breaking changes: incompatible config changes, renamed or removed commands/arguments, behavior semantics changes, and similar |
+
+### Major Rule
+
+Never write `major` on your own.
+
+If you believe a change qualifies as major, stop first, explain why, and ask the user for confirmation. Only write `major` after the user explicitly agrees. If the user does not reply, replies ambiguously, or disagrees, fall back to `minor`; if `minor` is also unclear, fall back to `patch`.
+
+## Wording Rules
+
+- Changelog entries **must be written in English**.
+- **Keep it short — ideally a single sentence that states what was done.** Do not write a paragraph, do not pile on technical detail, and do not enumerate every sub-change.
+- User-facing CLI wording should only be used when CLI users can perceive the change.
+- Internal changes that do not affect CLI users can still share a changeset with the CLI, but the wording must describe the real change honestly and must not present it as a user-facing feature.
+- Do not mention file names, class names, function names, PR numbers, or commit hashes.
+- Do not include real internal endpoints, key names, account names, or service names. If an example is needed, use neutral placeholders such as `example.com`, `example.test`, or `YOUR_API_KEY`.
+- Avoid vague words such as `refactor`, `optimize`, and `improve`. Describe the actual change, or use more specific wording.
+
+## Common Examples
+
+An internal package fixes a bug visible to CLI users:
+
+```markdown
+---
+"@pythoughts/pythinker-code": patch
+---
+
+Fix occasional loss of tool call results in long conversations.
+```
+
+An internal package has an internal-only change, but it enters the CLI bundle:
+
+```markdown
+---
+"@pythoughts/pythinker-code": patch
+---
+
+Unify tool execution metadata handling.
+```
+
+Only SDK source changed, and the CLI does not use it:
+
+```markdown
+---
+"@pythoughts/pythinker-code-sdk": patch
+---
+
+Clarify session status typing for internal SDK callers.
+```
+
+## Web app changes
+
+`@pythoughts/pythinker-web` is ignored by changesets and must **never** appear in a changeset frontmatter. Because the web app is bundled into the CLI release artifact, any web change that ships must list `@pythoughts/pythinker-code` instead and describe the actual web-facing change in the text.
+
+- If a PR contains both web UI changes and server API changes, split them into separate changesets so each entry has a focused description.
+- Do not enumerate every micro-tweak; keep it to one sentence that captures what the web user gets.
+
+Web-only fix:
+
+```markdown
+---
+"@pythoughts/pythinker-code": patch
+---
+
+Fix the web chat not scrolling to the bottom after sending a message.
+```
+
+Web UI plus server APIs in the same PR (split into two changesets):
+
+```markdown
+---
+"@pythoughts/pythinker-code": minor
+---
+
+Add the server-hosted web UI, including chat layout and session list behaviors.
+```
+
+```markdown
+---
+"@pythoughts/pythinker-code": minor
+---
+
+Add the server REST and WebSocket APIs that power the web UI.
+```
+
+## Red Flags
+
+- You are about to write `major` without asking the user.
+- Internal package source enters the CLI bundle, but `@pythoughts/pythinker-code` is missing.
+- A changeset frontmatter mixes ignored internal packages with non-ignored packages.
+- `packages/node-sdk` was not changed, but `@pythoughts/pythinker-code-sdk` was listed for "internal package sync".
+- The changelog entry is in Chinese.
+- The wording claims more than the diff actually did.
+- The CLI wording mentions internal package names, class names, or PR numbers.
+- The entry includes real internal identifiers instead of neutral placeholders.

.agents/skills/gen-docs/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: gen-docs
+description: Update Pythinker Code CLI user documentation after meaningful code changes that affect product behavior or user experience.
+---
+
+# Gen Docs
+
+## Overview
+
+This repository maintains English user documentation under `docs/`.
+
+Use this skill to update the corresponding documentation whenever the codebase has changes that affect product behavior or user experience.
+
+For a **full pre-release audit** of all pages (detecting hallucinations and coverage gaps), use the `audit-docs` skill instead.
+
+## Prerequisites
+
+This skill depends on the following being in place. If any are missing, stop and report to the user before continuing:
+
+- `docs/` directory with documentation pages and `docs/.vitepress/config.ts` set up (VitePress site).
+- `docs/AGENTS.md` style guide — defines terminology, typography, and writing style.
+
+## Workflow
+
+1. **Inspect changes**
+
+   - `git log main..HEAD --oneline` — commits on the current branch
+   - `git diff main..HEAD --stat` — file-level scope
+   - `ls .changeset/*.md` (excluding `README.md`) — pending changeset entries
+   - Read `CHANGELOG.md` and any subpackage `packages/*/CHANGELOG.md` for already-recorded entries.
+
+2. **Understand user-facing impact**
+
+   For each change, read the actual implementation when needed; **do not infer behavior from commit messages or PR titles alone**. Skip:
+
+   - Internal refactors with no externally visible behavior change
+   - Tests, CI, type-only changes
+   - Tooling / build-system changes that do not change how users invoke the CLI
+
+   If after the scan you conclude there is no user-facing impact, say so and stop.
+
+3. **Keep release changelog syncing separate**
+
+   Do not copy unreleased changesets into `docs/release-notes/changelog.md`. After a release is published, use the `sync-changelog` skill to sync `apps/pythinker-code/CHANGELOG.md` into the docs site with release dates and section classification.
+
+4. **Update user docs**
+
+   Following the rules in `docs/AGENTS.md`, edit the affected pages under `docs/`. Match terminology with the term table in `docs/AGENTS.md` and the existing wording in surrounding pages.
+
+   Cover all relevant sections:
+
+   - Guides (getting-started, use cases, interaction, sessions, IDE integration)
+   - Customization (skills, agents, MCP, hooks, plugins, etc.)
+   - Configuration (config files, env vars, providers, data locations)
+   - Reference (CLI subcommands, slash commands, keyboard shortcuts)
+   - Release notes (`docs/release-notes/breaking-changes.md` if a breaking change is involved)
+
+## Rules and conventions
+
+- **Terminology**: Use the term table in `docs/AGENTS.md` exactly. Do not invent synonyms.
+- **Scope discipline**: Only update sections affected by the recent changes. Do not opportunistically rewrite unrelated docs.
+- **Public examples**: Never write real internal endpoints, key names, account names, or service names into docs. Use neutral placeholders such as `https://api.example.com/v1`, `https://registry.example.com/v1/models/api.json`, `example.test`, and `YOUR_API_KEY`.
+- **Breaking changes**: If any change is breaking, also update `docs/release-notes/breaking-changes.md` (under `## Unreleased`) with `**Affected**` + `**Migration**` subsections.
+- **Do not edit auto-synced files**: `docs/release-notes/changelog.md` is regenerated by the sync script; any manual edit will be overwritten.
+
+## Common mistakes
+
+- Describing what code changed instead of what the user can now do (or can no longer do).
+- Adding a new section heading per feature instead of weaving the change into existing prose.

.agents/skills/opentui/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: opentui
+description: Build terminal UIs with OpenTUI. Covers core, components, audio, keymaps, React, Solid, plugins, testing, standalone executables, QR encoding, SSH, and Three.js WebGPU.
+---
+
+# OpenTUI Skill
+
+Canonical reference docs are authored once in sibling `docs/**/*.mdx` files.
+
+Inside the OpenTUI repo, this skill root lives at `packages/web/src/content/`, so the same files are also visible at `packages/web/src/content/docs/**/*.mdx`.
+
+## Path invariant
+
+- `/docs/<slug>` maps to `docs/<slug>.mdx` relative to this skill root
+- in the repo, that same slug maps to `packages/web/src/content/docs/<slug>.mdx`
+
+## Reading order by area
+
+- Getting started: `/docs/getting-started`
+- Core: `/docs/core-concepts/renderer`
+- Testing: `/docs/core-concepts/testing`
+- Audio: `/docs/core-concepts/audio`
+- Keymap: `/docs/keymap/overview`
+- React: `/docs/bindings/react`
+- Solid: `/docs/bindings/solid`
+- Components: `/docs/components/text`, `/docs/components/input`
+- Layout: `/docs/core-concepts/layout`
+- Keyboard: `/docs/core-concepts/keyboard`
+- Plugins: `/docs/plugins/slots`
+- Runtime and packaging: `/docs/reference/env-vars`, `/docs/reference/standalone-executables`
+- Package entrypoints: `/docs/reference/package-entrypoints`
+- QR encoding: `/docs/reference/qr-encoder`
+- SSH: `/docs/reference/ssh`
+- Three.js WebGPU: `/docs/reference/three`
+
+## Quick routing by intent
+
+| Intent(s)                                                                                          | Start here                                  |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `getting-started`, `installation`, `quickstart`, `intro`                                           | `docs/getting-started.mdx`                  |
+| `core`, `renderer`, `terminal`, `scrollback`, `lifecycle`                                          | `docs/core-concepts/renderer.mdx`           |
+| `audio`, `native-audio`, `sound`, `playback`, `streaming`, `radio`, `mp3`, `flac`, `pcm`, `fft`    | `docs/core-concepts/audio.mdx`              |
+| `keymap`, `keybindings`, `shortcuts`, `commands`, `leader`, `ex-commands`                          | `docs/keymap/overview.mdx`                  |
+| `layout`, `flexbox`, `yoga`, `positioning`                                                         | `docs/core-concepts/layout.mdx`             |
+| `keyboard`, `input`, `keybindings`, `paste`, `focus`                                               | `docs/core-concepts/keyboard.mdx`           |
+| `testing`, `test-renderer`, `snapshots`, `frames`                                                  | `docs/core-concepts/testing.mdx`            |
+| `react`, `jsx`, `hooks`, `keyboard`, `paste`, `focus`, `blur`, `selection`, `animation`, `testing` | `docs/bindings/react.mdx`                   |
+| `solid`, `jsx`, `signals`, `hooks`, `keyboard`, `animation`, `testing`                             | `docs/bindings/solid.mdx`                   |
+| `plugins`, `plugin`, `slots`, `registry`, `extensions`                                             | `docs/plugins/slots.mdx`                    |
+| `text`, `styling`, `content`, `selection`                                                          | `docs/components/text.mdx`                  |
+| `input`, `form`, `editing`, `focus`                                                                | `docs/components/input.mdx`                 |
+| `env`, `environment`, `configuration`, `flags`                                                     | `docs/reference/env-vars.mdx`               |
+| `standalone`, `executable`, `bun-compile`, `node-sea`, `node-assets`                               | `docs/reference/standalone-executables.mdx` |
+| `package-exports`, `entrypoints`, `subpath-exports`, `imports`                                     | `docs/reference/package-entrypoints.mdx`    |
+| `qr`, `qrcode`, `qr-encoder`, `svg-qr`, `gs1`, `eci`, `structured-append`                          | `docs/reference/qr-encoder.mdx`             |
+| `ssh`, `remote-tui`, `ssh-server`, `authentication`, `middleware`                                  | `docs/reference/ssh.mdx`                    |
+| `three`, `threejs`, `webgpu`, `3d`, `sprites`, `physics`                                           | `docs/reference/three.mdx`                  |
+
+For concrete component requests, jump straight to `docs/components/<name>.mdx` after the relevant entry page. For plugin implementation details, narrow from `docs/plugins/slots.mdx` into `docs/plugins/core.mdx`, `docs/plugins/react.mdx`, or `docs/plugins/solid.mdx`.
+
+## Current skill entry pages
+
+- `docs/getting-started.mdx`
+- `docs/core-concepts/renderer.mdx`
+- `docs/core-concepts/audio.mdx`
+- `docs/core-concepts/testing.mdx`
+- `docs/keymap/overview.mdx`
+- `docs/core-concepts/layout.mdx`
+- `docs/core-concepts/keyboard.mdx`
+- `docs/bindings/react.mdx`
+- `docs/bindings/solid.mdx`
+- `docs/plugins/slots.mdx`
+- `docs/components/text.mdx`
+- `docs/components/input.mdx`
+- `docs/reference/env-vars.mdx`
+- `docs/reference/standalone-executables.mdx`
+- `docs/reference/package-entrypoints.mdx`
+- `docs/reference/qr-encoder.mdx`
+- `docs/reference/ssh.mdx`
+- `docs/reference/three.mdx`
+
+## Working rules
+
+- Prefer the current entry pages first, then read narrower docs in the same section.
+- Read the sibling `docs/**/*.mdx` files directly instead of copying prose into this file.
+- Use stable `/docs/...` URLs when cross-referencing docs.