@laitszkin/apollo-toolkit 3.8.2 → 3.8.4

package/maintain-project-constraints/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maintain-project-constraints
-description: Automatically create and maintain AGENTS.md/CLAUDE.md so it stays aligned with the current repository architecture, core business flow, common commands, macro project purpose, and coding conventions. Use when AGENTS.md/CLAUDE.md is missing or may be outdated after code changes.
+description: Create and maintain AGENTS.md/CLAUDE.md with the project's macro business goals, common development commands, and an index of all standardized project documentation under docs/. Use when AGENTS.md/CLAUDE.md is missing or may be outdated.
 ---
 
 # Maintain Project Constraints
@@ -14,130 +14,132 @@ description: Automatically create and maintain AGENTS.md/CLAUDE.md so it stays a
 
 ## Standards
 
-- Evidence: Infer repository architecture, business flow, and conventions from current code and docs rather than assumptions.
-- Execution: Create or align `AGENTS.md/CLAUDE.md` only after building a concrete inventory of implemented capabilities.
-- Quality: Keep every statement traceable, remove stale guidance, and ensure `Core business flow` stays exhaustive and concrete.
-- Output: Maintain a concise root-level `AGENTS.md/CLAUDE.md` with the required sections, repository-specific wording, and a factual `Common Commands` section when the repository exposes stable command entry points.
+- Evidence: Infer project business goals and common commands from current code, configuration, and existing project documentation — not assumptions.
+- Execution: Read the entire codebase or existing project docs before writing; create or update only after building a concrete inventory.
+- Quality: Remove stale commands, paths, and references; keep AGENTS.md/CLAUDE.md focused on the three required sections only.
+- Output: Maintain a concise root-level `AGENTS.md`/`CLAUDE.md` with common development commands, macro business goals, and a project documentation index.
 
 ## Goal
 
-Keep `AGENTS.md/CLAUDE.md` accurate, actionable, and synchronized with the latest state of the repository.
+Keep `AGENTS.md`/`CLAUDE.md` accurate and synchronized with the current state of the repository, focused on helping agents understand the project's purpose, navigate its documentation, and run common development tasks.
 
 ## Trigger Conditions
 
-Invoke this skill when either condition is true:
+Invoke this skill when:
 
-1. `AGENTS.md/CLAUDE.md` does not exist and the user needs this repository to expose agent-facing guidance.
-2. `AGENTS.md/CLAUDE.md` exists but may have drifted after code changes, refactors, or workflow updates.
+1. `AGENTS.md` or `CLAUDE.md` does not exist.
+2. `AGENTS.md` or `CLAUDE.md` exists but may have drifted after code changes, documentation updates, or workflow changes.
+3. After `align-project-documents` has updated the `docs/` structure and the document index needs to be refreshed.
 
-After completing any code modification task, proactively run this skill to verify `AGENTS.md/CLAUDE.md` is still aligned, and update it if needed.
+## Required Output Format
 
-## Required Outputs
+`AGENTS.md`/`CLAUDE.md` must contain exactly three sections:
 
-`AGENTS.md/CLAUDE.md` must include these sections (use concise, repository-specific content):
+### 1. Common Development Commands
 
-- Project architecture
-- Core business flow
-- Common commands
-- Core project purpose
-- Code style and coding conventions
+- Include only commands that are real, current, and useful in this repository.
+- Prefer repository-owned entry points: package scripts, CLIs, `bin/` programs, `scripts/`, `Makefile`, `justfile`, or equivalent task runners.
+- For each command, explain when to use it in one short phrase.
+- Prioritize commands that help an agent inspect, validate, build, test, or operate the repository.
+- Do not invent commands, aliases, flags, or task names not traceable to the repository.
 
-For the `Core project purpose` section, always use this format:
+### 2. Project Business Goals
 
-1. Describe the repository's macro purpose instead of repeating implemented features.
-2. State what broader problem the project is meant to solve or what outcome it aims to achieve.
-3. Prefer product- or business-level intent framing when applicable.
-4. Keep it concise, but make sure the purpose is understandable without reading the rest of the document.
+- Describe the project's macro business purpose: what problem it solves, what outcome it aims to achieve, who it serves.
+- Write at the product or business level, not at the implementation level.
+- Keep it concise but self-contained — a reader should understand why the project exists without reading other documents.
 
-For the `Common Commands` section, always use this format:
+### 3. Project Documentation Index
 
-1. Include only commands that are real, current, and useful in this repository.
-2. Prefer repository-owned entry points such as package scripts, CLIs, `bin/` programs, `scripts/`, `Makefile`, `justfile`, or other documented task runners.
-3. For each command, explain when to use it in one short phrase instead of listing bare commands with no context.
-4. Prioritize commands that help an agent inspect, validate, build, test, or operate repository-specific workflows.
-5. Do not invent commands, aliases, flags, or task names that are not traceable to the repository.
+- List all standardized project documentation files under `docs/`.
+- Organize by category: `docs/features/`, `docs/architecture/`, `docs/principles/`.
+- For each document, provide the file path and a one-line description of what it covers.
+- List any additional root-level documentation files (e.g., `README.md`, `CONTRIBUTING.md`, `SECURITY.md`).
 
-For the `Core business flow` section, always use this format:
-
-1. One short sentence that summarizes what the repository currently enables.
-2. An exhaustive unordered list of the repository's current existing functions/capabilities.
-3. Each bullet must be a short capability statement, preferably in the style of `- Users can ...` or the repository-equivalent actor phrasing.
-
-Example:
+### Template Example
 
 ```markdown
+## Common Development Commands
 
-## Common Commands
-
-- `npm test` — run the repository's automated test suite.
+- `npm test` — run the test suite.
+- `npm run build` — compile the project for production.
 - `apltk validate-skill-frontmatter` — validate every top-level `SKILL.md` frontmatter block.
-- `apltk validate-openai-agent-config` — validate every `agents/openai.yaml` interface config.
-- `apltk codex` — install the current toolkit into the local Codex skills directory.
 
-## Core Business Flow
+## Project Business Goals
 
 This project enables users to manage and run reusable automation workflows.
+It solves the problem of scattered, inconsistent automation scripts by providing a unified catalog of versioned, validated skills.
+
+## Project Documentation Index
+
+### Features (`docs/features/`)
+
+- `docs/features/skill-management.md` — skill creation, editing, and lifecycle management
+- `docs/features/validation.md` — skill and configuration validation workflows
+
+### Architecture (`docs/architecture/`)
+
+- `docs/architecture/skill-system.md` — skill loading, resolution, and execution model
+- `docs/architecture/validation-pipeline.md` — validation pipeline design
+
+### Principles (`docs/principles/`)
+
+- `docs/principles/naming-conventions.md` — file and identifier naming rules
+- `docs/principles/dependency-management.md` — internal and external dependency rules
+
+### Root Documents
 
-- Users can create a workflow from a local template.
-- Users can update an existing workflow configuration.
-- Users can validate workflow inputs before execution.
-- Users can run the workflow and inspect the result.
+- `README.md` — project overview and quick start
 ```
 
 ## Workflow
 
-### 1) Build factual understanding first
+### 1) Build factual understanding
 
-- Confirm whether `AGENTS.md/CLAUDE.md` exists.
-- Read the repository before writing:
-  - root docs (`README`, contribution docs, design docs)
-  - key source directories and entry points
-  - repository command surfaces such as `package.json`, `bin/`, `scripts/`, `Makefile`, `justfile`, or equivalent task runners
-  - user-facing features such as commands, routes, workflows, tasks, or installable modules
-  - representative modules that show coding patterns
-  - test directories and tooling/config files
-- Infer architecture and conventions from real code, not assumptions.
-- Build a concrete inventory of all currently implemented capabilities before drafting `Core business flow`.
-- Build a separate inventory of stable, repository-specific commands before drafting `Common Commands`.
+- Read the repository entry points, configuration, and command surfaces (`package.json`, `bin/`, `scripts/`, `Makefile`, etc.).
+- If standardized project documentation exists under `docs/`, read `docs/features/`, `docs/architecture/`, and `docs/principles/` to understand the documented capabilities and to build the index.
+- If `docs/` does not exist or is incomplete, read the source code directly to extract business goals and common commands.
+- Build a concrete inventory of:
+  - Every stable, repository-specific command.
+  - The project's macro business purpose (from docs, README, or inferred from the codebase's capabilities).
+  - Every file under `docs/` that should appear in the index.
 
-### 2) Create AGENTS.md/CLAUDE.md when missing
+### 2) Extract macro business goals
 
-When `AGENTS.md/CLAUDE.md` is absent:
+- Derive the project's business purpose from:
+  1. Existing documentation (`README.md`, `docs/features/`) if available.
+  2. The set of user-facing capabilities found in the codebase.
+- Write at the product level: what problem does this solve? who uses it? what outcome does it produce?
+- Do not restate implementation details or list features; the document index already points to feature docs.
 
-- Create a new root-level `AGENTS.md/CLAUDE.md`.
-- Document architecture, business flow, purpose, and coding conventions from observed facts.
-- Write `Core project purpose` as the repository's macro intent, such as the problem it aims to solve or the outcome it exists to achieve, rather than as a feature list.
-- Document the repository's common commands from observed command entry points and docs.
-- Write `Core business flow` as one summary sentence followed by unordered bullets that cover every current capability found in the repository.
-- Write `Common commands` as short bullets in the style of ``- `command` — when to use it.``.
-- Keep language specific to this repository; avoid generic boilerplate.
+### 3) Write or update AGENTS.md/CLAUDE.md
 
-### 3) Align AGENTS.md/CLAUDE.md when drift is detected
+- If `AGENTS.md` exists, update it. If `CLAUDE.md` exists, update it. If both exist, update both with identical content for the three sections.
+- If neither exists, check for the repository's convention and create the appropriate file.
+- Write only the three sections: Common Development Commands, Project Business Goals, Project Documentation Index.
+- Do not add architecture descriptions, code style guidance, business flows, or any content that belongs in `docs/`.
 
-When `AGENTS.md/CLAUDE.md` exists but is outdated:
+### 4) Maintain the project documentation index
 
-- Re-read changed or high-impact modules.
-- Update only sections that no longer match reality.
-- Expand or trim the `Core business flow` bullet list so it still covers all currently implemented capabilities.
-- Expand, trim, or replace the `Common Commands` list whenever command entry points or recommended workflows have changed.
-- Preserve correct existing content and structure where possible.
+- Enumerate every file under `docs/features/`, `docs/architecture/`, and `docs/principles/`.
+- For each file, write a one-line description of what it covers.
+- List root-level documentation files (`README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, etc.) that exist in the repository.
+- Keep the index synchronized with the actual files on disk; remove entries for deleted files and add entries for new files.
 
-### 4) Quality checks before finishing
+### 5) Quality checks before finishing
 
-- Ensure every statement in `AGENTS.md/CLAUDE.md` is traceable to current repository files.
-- Remove stale paths, renamed components, and obsolete workflows.
-- Remove stale commands, flags, or task names that no longer exist.
-- Verify every command in `Common Commands` is either documented in repository docs or directly supported by the current codebase.
-- Verify the `Core business flow` section includes a one-sentence summary plus unordered bullets for all currently existing capabilities; do not leave major functions unlisted.
-- Verify `Core project purpose` explains the repository's macro goal and does not merely restate the feature inventory.
-- Keep instructions concise, concrete, and operational for future agents.
+- Verify every command in Common Development Commands is traceable to a repository entry point.
+- Verify Project Business Goals describes the macro purpose, not a feature list.
+- Verify every file listed in the Documentation Index exists on disk.
+- Verify the index covers all files under `docs/features/`, `docs/architecture/`, and `docs/principles/`.
+- If both `AGENTS.md` and `CLAUDE.md` exist, verify their content is consistent.
+- Remove any sections beyond the three required ones.
 
 ## Writing Rules
 
-- Use clear headings and short bullet points.
-- Prefer repository terms already used in code/docs.
-- Do not include speculative architecture claims.
-- In `Core project purpose`, describe why the project exists at a macro level; for example, what user or business problem it solves, not a restatement of `Core business flow`.
-- In `Core business flow`, prefer many short bullets over a few vague bullets; when the product grows, add more bullets so the list remains exhaustive.
-- In `Common Commands`, prefer the smallest useful set of high-signal commands over an exhaustive dump of every helper script.
-- Keep the document focused on how agents should understand and operate in this project.
+- Keep the document concise and scannable.
+- Use the repository's own terminology.
+- Do not speculate about architecture or implementation details.
+- In Project Business Goals, describe the macro purpose; for example, the user or business problem the project solves.
+- In the Documentation Index, prefer descriptive one-line summaries over bare file paths.
+- When both `AGENTS.md` and `CLAUDE.md` exist, keep their content identical for the three sections.

package/maintain-project-constraints/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Maintain Project Constraints"
-  short_description: "Automatically create and maintain AGENTS.md/CLAUDE.md so it stays aligned with the current repository architecture, core business flow, common commands, macro project purpose, and coding conventions. Use when AGENTS.md/CLAUDE.md is missing or may be outdated after code changes."
-  default_prompt: "Use $maintain-project-constraints to automatically create and maintain AGENTS.md/CLAUDE.md so it stays aligned with the current repository architecture, core business flow, common commands, macro project purpose, and coding conventions. Use when AGENTS.md/CLAUDE.md is missing or may be outdated after code changes."
+  short_description: "Create and maintain AGENTS.md/CLAUDE.md with business goals, common commands, and project doc index"
+  default_prompt: "Use $maintain-project-constraints to read the codebase or existing project docs, extract the project's macro business goals, inventory common development commands, enumerate all standardized docs under docs/features/, docs/architecture/, and docs/principles/, then write or update AGENTS.md/CLAUDE.md with exactly three sections: Common Development Commands, Project Business Goals, and Project Documentation Index. If both AGENTS.md and CLAUDE.md exist, keep their content consistent."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.8.2",
+  "version": "3.8.4",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/align-project-documents/references/templates/category-based-project-docs-template.md

@@ -1,170 +0,0 @@
-# Category-Based Project Documentation Template
-
-Use this template as a selection guide, not a mandatory outline. Start by classifying the repository's real content and the readers' likely questions, then choose only the document categories and section blocks that are actually supported by evidence.
-
-Base the classification on common open source documentation practice:
-
-- Use the Diataxis content families when deciding what kind of content you are writing: tutorial, how-to, reference, and explanation.
-- Use common open source repository documents when deciding where the content should live: `README`, `CONTRIBUTING`, `SECURITY`, `CODE_OF_CONDUCT`, troubleshooting guides, glossary, and release notes when applicable.
-- Use The Good Docs Project templates as a practical guide for selecting content types that teams repeatedly need in real projects.
-
-## 1. Start With Reader And Content Classification
-
-Before writing, identify:
-
-| Classification | Questions to answer | Example answers |
-| --- | --- | --- |
-| Primary readers | Who needs this document first? | New developer, operator, support teammate, PM, founder |
-| Reader background | What might they not know yet? | No repo context, no local setup experience, no domain knowledge |
-| Main job to be done | What is the reader trying to accomplish? | Run locally, change a feature, deploy, debug an incident |
-| Evidence sources | Which files prove the behavior? | `README.md`, `package.json`, `src/server.ts`, `.github/workflows/deploy.yml` |
-| Documentation risk | What would go wrong if this is undocumented? | Broken onboarding, misconfigured secrets, incorrect production operation |
-
-Write the document around the real questions above. Do not force a category or section when the repository does not support it.
-
-## 2. Choose The Right Document Categories
-
-Select one or more categories below. Keep the titles content-led and specific. Prefer titles such as `本地啟動後端服務`, `設定 Stripe 測試金鑰`, or `訂單同步失敗時如何排查`, instead of generic headings that hide the real task.
-
-| Open source documentation type | Diataxis family | Use when the repository contains... | Main reader need | Suggested output path |
-| --- | --- | --- | --- |
-| README / docs index | Mixed entrypoint | Clear project purpose, user value, repo scope, key links | "What is this project and where do I start?" | `README.md`, `docs/README.md` |
-| Tutorial / getting started | Tutorial | A first-run path that teaches by doing | "Help me complete my first successful run." | `docs/getting-started.md`, `docs/tutorials/*.md` |
-| How-to / runbook / operations guide | How-to | Repeated workflows, CLI commands, dashboards, jobs, support actions | "How do I perform this real task?" | `docs/how-to/*.md`, `docs/runbooks/*.md`, `docs/operations.md` |
-| Reference / configuration catalog | Reference | Env vars, config files, commands, endpoints, state tables, limits | "What options, inputs, or values exist?" | `docs/configuration.md`, `docs/reference/*.md` |
-| Explanation / architecture / concepts | Explanation | Module boundaries, data flow, ownership, state transitions, tradeoffs | "How is this built and why is it shaped this way?" | `docs/architecture.md`, `docs/concepts/*.md` |
-| Troubleshooting | How-to + reference | Known symptoms, causes, checks, recovery actions | "What should I check when it breaks?" | `docs/troubleshooting.md`, `docs/runbooks/*.md` |
-| CONTRIBUTING | How-to + explanation | Contribution flow, local validation, review expectations | "How do I contribute safely?" | `CONTRIBUTING.md`, `docs/developer-guide.md` |
-| SECURITY | How-to + reference | Vulnerability reporting process, supported versions, security boundaries | "How should I report a security issue?" | `SECURITY.md` |
-| CODE_OF_CONDUCT | Community governance | Community expectations and reporting path | "How does this project expect people to behave?" | `CODE_OF_CONDUCT.md` |
-| Glossary / terminology | Reference | Business rules, lifecycle states, project vocabulary, permissions | "What do these terms mean?" | `docs/glossary.md`, `docs/terminology.md` |
-| FAQ / decisions / release notes | Explanation + reference | Repeated questions, key tradeoffs, notable changes | "Why was this choice made?" / "What changed?" | `docs/faq.md`, `docs/decisions/*.md`, `CHANGELOG.md` |
-
-### Selection Rules
-
-- Start by asking which Diataxis family the content belongs to.
-- Then choose the most conventional open source document type that readers would expect to find.
-- Do not merge tutorial, how-to, reference, and explanation into one page unless the repository is genuinely small enough that separation would hurt readability.
-- Keep community-governance documents such as `CONTRIBUTING`, `SECURITY`, and `CODE_OF_CONDUCT` separate from product usage docs.
-- When a document mixes content types, decide which type is primary and move the rest behind links.
-
-## 3. Section Blocks You Can Reuse Inside Any Document
-
-Use only the blocks that help the target reader. Rename each heading to match the specific content.
-
-### A. Reader Context Block
-
-Use when the reader may not understand the project or task yet.
-
-- Who should read this:
-- What they are probably trying to do:
-- What they need to know first:
-- What success looks like after reading:
-
-### B. Before You Start Block
-
-Use for setup, operations, deployments, or debugging.
-
-- Required tools or accounts:
-- Required permissions or credentials:
-- Files, services, or environments involved:
-- Safe test or sandbox alternatives:
-
-### C. Exact Steps Block
-
-Use for any task-oriented content.
-
-1. State the action in plain language.
-2. Give the exact command, UI path, or file path.
-3. Explain what result should appear.
-4. Explain what to do if the result does not appear.
-
-### D. Expected Signals Block
-
-Use when readers need to confirm they are on the right path.
-
-- Success logs, UI states, API responses, artifacts, or screenshots:
-- Expected side effects:
-- How long the step usually takes:
-
-### E. Failure And Recovery Block
-
-Use when the workflow can fail or confuse newcomers.
-
-- Common mistake:
-- Symptom:
-- Likely cause:
-- How to verify:
-- How to fix:
-
-### F. Code Navigation Block
-
-Use for architecture or developer-facing docs.
-
-- Entry point:
-- Main modules and responsibilities:
-- Important data models:
-- External integration touchpoints:
-- Highest-risk files to review before editing:
-
-### G. Decision And Limitation Block
-
-Use when the code or operations include tradeoffs.
-
-- Current limitation:
-- Why it exists:
-- When it matters:
-- Safe workaround:
-- Evidence:
-
-## 4. Newcomer-Friendly Writing Rules
-
-Every non-trivial document should help a reader who does not yet know the project. Prefer explaining:
-
-- what this part of the system is for
-- why the reader would need it
-- what they must prepare beforehand
-- what exact action they should take
-- what result they should expect
-- what usually goes wrong
-- where in the repository the truth lives
-
-Avoid:
-
-- headings that only repeat template words without conveying meaning
-- assuming the reader already knows internal jargon
-- mentioning files, services, or commands without saying why they matter
-- mixing future plans with current behavior
-
-## 5. Evidence Checklist
-
-Before finishing, confirm:
-
-- every important instruction maps to code, config, scripts, tests, or current deployment files
-- every command is current and runnable, or explicitly marked as needing manual confirmation
-- each document category exists because the repository actually needs it
-- each heading is descriptive of the real content, not just copied from a template
-- unknowns are labeled clearly instead of guessed
-
-## 6. Example Of Category Selection
-
-Example classification:
-
-- Readers: new developer and part-time operator
-- Main needs: local startup, environment configuration, order sync debugging
-- Repository evidence: API server, worker process, queue config, deploy workflow, sync failure logs
-
-Reasonable outputs:
-
-- `README.md`: project overview and links
-- `docs/getting-started.md`: tutorial-style first successful run
-- `docs/configuration.md`: reference-style env vars and third-party credentials
-- `docs/architecture.md`: explanation of API, worker, queue, and database boundaries
-- `docs/runbooks/order-sync-failures.md`: how-to troubleshooting for order sync issues
-- `CONTRIBUTING.md`: contribution flow, local checks, and review expectations if external contributors are expected
-
-Not needed unless evidence supports them:
-
-- `docs/glossary.md`
-- `docs/faq.md`
-- separate feature catalog for every route/page

package/archive-specs/references/templates/configuration.md

@@ -1,29 +0,0 @@
-# Configuration
-
-## 1. Environment Variables And Config Files
-
-| Key / File | Required | Purpose | Example / Default | Evidence |
-| --- | --- | --- | --- | --- |
-| `[ENV_KEY]` | `[Yes/No]` | [What it controls] | [Example or default] | [File path] |
-| `[config/file]` | `[Yes/No]` | [Why it matters] | [Example or default] | [File path] |
-
-## 2. External Services And Credential Setup
-
-### [Service Name]
-
-- Purpose: [Why this service exists in the project]
-- Required keys/config: `[ENV_KEY]`, `[CONFIG_KEY]`
-- Official setup entry: [Link or exact console path if known]
-- Acquisition steps:
-  1. [Create or open the relevant account/project]
-  2. [Generate/find the credential]
-  3. [Store it in the local/deployment config]
-  4. [Verify connectivity]
-- Development notes: [sandbox/test mode, rate limit, fake data, or `Unknown`]
-- Evidence: [file path or spec path]
-
-## 3. Safety Notes
-
-- Secret handling: [where secrets should live]
-- Local overrides: [env file / config layering / secret manager]
-- Common misconfiguration symptoms: [brief list]

package/archive-specs/references/templates/developer-guide.md

@@ -1,33 +0,0 @@
-# Developer Guide
-
-## 1. Domain Concepts To Know
-
-- [Business rule, glossary term, permission model, lifecycle concept]
-- [Business rule, glossary term, permission model, lifecycle concept]
-
-## 2. Change Hotspots
-
-- Critical modules: [paths or module names]
-- External dependency touchpoints: [APIs/services/jobs]
-- Data integrity or migration risks: [if any]
-- Concurrency / idempotency concerns: [if any]
-
-## 3. Testing Expectations
-
-- Required test layers: [unit / integration / E2E / property-based]
-- Mock/fake expectations: [where external dependencies should be isolated]
-- High-value regression areas: [bug-prone workflows]
-
-## 4. Debugging Entry Points
-
-- Logs: [paths / commands / tools]
-- Local reproduction commands: [commands]
-- Dashboards or observability tools: [if any]
-- Common failure signals: [errors / symptoms]
-
-## 5. Documentation Maintenance Notes
-
-- Specs reviewed: [list of spec directories/files]
-- Existing docs updated: [paths]
-- Major conflicts resolved: [spec vs code decisions]
-- Remaining unknowns: [list or `None`]

package/archive-specs/references/templates/getting-started.md

@@ -1,38 +0,0 @@
-# Getting Started
-
-## 1. Purpose
-
-- Project purpose: [What the project exists to do]
-- Primary users: [Who uses it]
-- Supported environments: [local / staging / production / other]
-
-## 2. Prerequisites
-
-- Runtime/tooling: [Node/Python/Docker/etc.]
-- Accounts/services needed: [if any]
-- Local dependencies: [database, queue, browser, etc.]
-
-## 3. Installation
-
-```bash
-[Clone / install / bootstrap commands]
-```
-
-## 4. Local Run
-
-```bash
-[Run or dev server commands]
-```
-
-## 5. Deployment
-
-- Deployment targets: [where it deploys]
-- Deployment command or pipeline: [command / CI job / script]
-- Required pre-deploy checks: [tests, migrations, approvals]
-- Rollback notes: [how rollback works or `Unknown`]
-
-## 6. Verification
-
-- Smoke checks: [command / URL / workflow]
-- Expected signals: [log, page, API response, artifact]
-- Evidence: [file path or command path]