docs: add docs taxonomy workflow and initial ko/ja/fr translations

apps/docs/CONTRIBUTING.md

@@ -5,6 +5,58 @@
 - Translation - i18n support for your native language would be a great first choice.
 - Documentation - Improve the documentations
 
+## Source of truth
+
+- Edit docs in `/docs/**`.
+- Do not edit generated files in `/apps/docs/docs/**`.
+- Translations live next to their source docs under a sibling `translations/` directory and are copied into Docusaurus i18n output during `pnpm content:setup`.
+
+## Documentation taxonomy
+
+Use this workflow when deciding whether a doc should ship:
+
+- Ship docs that are already minimally meaningful. If the page is useful now, publish it now.
+- Use `draft: true` only when the page is not yet meaningful enough to ship.
+- Reserve `unlisted: true` for intentionally non-discoverable or on-demand docs. It is not the default for incomplete work.
+- Use the custom frontmatter field `doc_tasks` to track follow-up work on docs that still ship.
+
+Example:
+
+```md
+---
+title: Example
+description: One-line summary.
+doc_tasks:
+  - enhance
+  - translate
+format: md
+---
+```
+
+`doc_tasks` values:
+
+- `enhance` for pages that need stronger examples, screenshots, or structure
+- `update` for pages that should be checked against current product behavior or UI
+- `translate` for pages that should get priority locale coverage next
+
+## Translation workflow
+
+- Treat the main English doc in `/docs/**` as the source of truth. Translations flow from `en` to locale docs such as `ko`, `ja`, and `fr`; do not reverse-sync changes from a locale doc back into the English source by default.
+- Keep the source doc publishable even before translations exist.
+- Add `doc_tasks: [translate]` on the source doc when translation is still pending.
+- For a page like `docs/platform/index.md`, place the Korean translation at `docs/platform/translations/ko/index.md`.
+- Add `translations/meta.json` in that directory if it does not already exist.
+- Locale docs are copied into Docusaurus i18n output with the `translations/<locale>/` segment removed. Keep internal relative doc links aligned with the English source doc unless a translation intentionally changes the document structure.
+
+## Validation
+
+Before finishing docs work, run the docs site setup/build from `/apps/docs`:
+
+```sh
+pnpm content:setup
+pnpm build
+```
+
 ## Note for Insiders
 
 Beaware of two configurations, next.config.js (web : root) and docusaurus.config.js (docs-site : /docs).

apps/docs/README.md

@@ -2,6 +2,19 @@
 
 This website is built using [Docusaurus](https://docusaurus.io/).
 
+## Source docs and translations
+
+- Source docs live in the repository root under `/docs/**`.
+- `/apps/docs/docs/**` is generated during docs setup and build.
+- Locale files live in `translations/<locale>/` directories next to the source docs and are copied into Docusaurus i18n output.
+
+## Shipping rules
+
+- Publish docs once they are minimally meaningful.
+- Use `draft: true` only for docs that are not yet meaningful enough to ship.
+- Reserve `unlisted: true` for intentionally non-discoverable docs.
+- Use `doc_tasks` to track follow-up work on publishable docs: `enhance`, `update`, `translate`.
+
 ### Running locally
 
 ```sh

apps/docs/docusaurus.config.ts

@@ -57,11 +57,7 @@ const config: Config = {
   stylesheets: [require.resolve("katex/dist/katex.min.css")],
   i18n: {
     defaultLocale: "en",
-    locales: [
-      "en",
-      // "fr",
-      "ko",
-    ],
+    locales: ["en", "ja", "fr", "ko"],
   },
   themeConfig: {
     navbar: {

docs/AGENTS.md

@@ -34,6 +34,58 @@ frontmatter with `title`, `description`, and `keywords`. For most `wg/` and
 `reference/` Markdown pages that do not use MDX/JSX features, also include
 `format: md` as described below.
 
+## Doc taxonomy
+
+We use a simple shipping-first taxonomy for Docusaurus docs.
+
+- **Ship minimally meaningful docs.** If a doc already helps a user complete a task or understand a feature, publish it as a normal doc even if it still needs screenshots, examples, or polish.
+- **Use `draft: true` for docs that are not meaningful enough to ship yet.** Drafts are for placeholders, partial notes, or incomplete pages that would not yet help a user on their own.
+- **Do not use `unlisted: true` as the default state for incomplete docs.** `unlisted: true` is reserved for intentionally non-discoverable docs such as on-demand pages, historical records, or docs that should exist but stay out of navigation/search.
+- **Use `doc_tasks` for follow-up work on docs that still ship.** This is our custom frontmatter field for triage and task tracking.
+
+### `doc_tasks` frontmatter
+
+Use `doc_tasks` when a page is publishable now but still needs follow-up work.
+
+```md
+---
+title: Example doc
+description: Short summary of what the page covers.
+doc_tasks:
+  - enhance
+  - translate
+format: md
+---
+```
+
+Allowed values:
+
+- `enhance` — the doc ships, but needs better examples, screenshots, structure, or depth
+- `update` — the doc ships, but should be checked against current product behavior, APIs, or UI
+- `translate` — the source doc ships, but still needs priority translation work
+
+Guidelines:
+
+- Omit `doc_tasks` when no follow-up work needs to be tracked.
+- Prefer `doc_tasks` over `draft: true` when the page is already useful enough to publish.
+- Remove a task once that follow-up work is complete.
+
+## Authoring workflow
+
+When creating or revising a Docusaurus doc, use this decision flow:
+
+1. Is the page already minimally meaningful for its audience?
+   - If yes, ship it normally.
+   - If it still needs obvious follow-up work, add `doc_tasks`.
+2. Is the page not yet useful enough on its own?
+   - Add `draft: true`.
+3. Should the page exist but remain intentionally hard to discover?
+   - Use `unlisted: true`.
+4. Is the page a normal Markdown page without JSX/MDX features?
+   - Prefer `format: md`.
+5. Does the page have a Korean translation under a sibling `translations/ko/` directory?
+   - If not and translation is still desired, add `doc_tasks: [translate]` to the source doc.
+
 ## Special Cases
 
 Some docs trees are intentionally kept, but have different ownership rules:

docs/editor/features/tray.md

@@ -2,6 +2,9 @@
 title: Tray
 description: Organize your canvas with Trays — lightweight containers that group frames without affecting layout or exports.
 format: md
+doc_tasks:
+  - enhance
+  - translate
 ---
 
 # Tray

docs/editor/shortcuts/index.md

@@ -1,3 +1,17 @@
+---
+title: Grida Editor shortcuts
+description: Reference the keyboard shortcuts available in the Grida editor across tools, selection, editing, layout, and view controls.
+keywords:
+  - grida
+  - editor
+  - shortcuts
+  - keyboard shortcuts
+  - hotkeys
+format: md
+doc_tasks:
+  - update
+---
+
 # Grida Editor Shortcuts
 
 Welcome to the official keyboard shortcuts guide for the Grida Canvas Editor. This reference covers all available keyboard shortcuts to help you work more efficiently and navigate the editor with ease.