chore: import upstream snapshot with attribution

2026-07-13 12:23:40 +08:00
commit 3a28426bf4
1399 changed files with 257375 additions and 0 deletions
@@ -0,0 +1,47 @@
+---
+name: docs
+description: Use this skill when contributing to InsForge's product documentation in this repository. This is for maintainers editing public docs in `docs/core-concepts`, agent docs in `.agents/docs`, SDK integration guides in `docs/sdks`, and OpenAPI specs in `openapi`.
+---
+
+# InsForge Dev Docs
+
+Use this skill for `docs/core-concepts/`, `.agents/docs/`, `docs/sdks/`, and `openapi/` in the InsForge repository.
+
+The documentation in this repo is primarily product documentation for InsForge users and agents integrating with InsForge. This skill is for InsForge engineers maintaining that public documentation surface.
+
+## Scope
+
+- `docs/core-concepts/**`
+- `.agents/docs/**`
+- `docs/sdks/**`
+- `openapi/**`
+
+## Working Rules
+
+1. Put each document in the correct documentation surface.
+   - Human-friendly docs published on the public doc site belong in `docs/core-concepts/` and related public doc folders.
+   - For implementation-heavy public docs, prefer an `architecture.md` file inside the relevant `docs/core-concepts/<domain>/` folder.
+   - Agent-only instructions belong in `.agents/docs/`.
+   - SDK integration guides for each framework belong in `docs/sdks/`.
+   - OpenAPI contract changes belong in the matching files under `openapi/`.
+
+2. Match the writing style to the audience.
+   - Public docs should be human-friendly and explain the implementation clearly.
+   - Keep public docs human-sounding: avoid AI-writing tells such as em dashes, rule-of-three lists, "not just X but Y" parallelism, inflated significance, vague attribution, and AI vocabulary (delve, leverage, underscore, seamless, robust). See the `doc-author` skill's `INSFORGE.md` overlay, "Sound human, not AI-generated".
+   - `architecture.md` pages in `docs/core-concepts/` should explain how the feature works in detail.
+   - Agent docs in `.agents/docs/` should be instruction-first and execution-oriented.
+   - Agent docs should avoid explanatory filler and focus on the exact steps an agent should follow to complete the work.
+
+3. Prevent documentation drift on every implementation change.
+   - Before changing implementation, check the current user-facing docs for that feature.
+   - After changing implementation, update the relevant Markdown docs and the relevant OpenAPI YAML files in the same pass.
+   - Do not treat OpenAPI and Markdown as separate optional follow-ups when the feature contract or behavior changed.
+   - If a change affects agent workflows, update the corresponding file in `.agents/docs/`.
+   - If a change affects public product understanding, update the corresponding file in `docs/core-concepts/`, including `architecture.md` when implementation details changed.
+   - If a change affects SDK integration guidance, update the corresponding framework guide in `docs/sdks/`.
+
+## Validation
+
+- Re-read every documented command, path, route, and payload for correctness.
+- Cross-check OpenAPI YAML and Markdown docs against the implemented behavior before finishing.
+- Mention anything you could not verify directly.