docs: improve docs SEO and GEO

apps/docs/content/blog/en/ai-native-monorepo-cli.md

@@ -0,0 +1,48 @@
+---
+title: "What an AI-Native Monorepo CLI Needs to Control"
+description: "An AI-native monorepo CLI should give agents a stable workspace contract, not just a folder generator."
+date: "2026-05-17"
+author: "One CLI Team"
+tags: ["ai-native", "monorepo", "cli"]
+---
+
+## AI-native is an operating boundary
+
+An AI-native CLI is not only a command line tool that mentions agents. It is a tool that gives agents a stable boundary to operate inside. The important question is not whether an agent can edit files. The question is whether the agent can discover the workspace structure, understand which files are generated, run the right dependency commands, and report failures in a way that other tools can parse.
+
+For monorepos, this boundary matters more than usual. A single repository can contain a frontend, backend, documentation site, shared package, mobile app, and deployment config. Without a shared contract, every command and agent session starts by guessing.
+
+## What the CLI must make explicit
+
+One CLI treats the workspace manifest as the common contract. That means generated projects, template origin, package-manager choice, and operational intent are visible from structured data instead of scattered README prose.
+
+An AI-native monorepo CLI should make these facts explicit:
+
+- Where the workspace root is.
+- Which projects are apps, services, packages, or docs.
+- Which template created each project.
+- Which dependency toolchain applies to each project.
+- Which commands are safe to run automatically.
+- Which errors have stable machine-readable codes.
+
+This is why `one create`, `one add`, `one templates`, and JSON output are part of the same product surface. Scaffolding starts the workspace, but the contract keeps it maintainable after the first command finishes.
+
+## Why agents need more than README text
+
+A human can read a README, compare it with the file tree, and infer missing details. A coding agent can do that too, but the result is slower and less reliable. If the agent needs to decide whether to run `pnpm install` at the root or `go mod download` inside a service, guessing from folders is not good enough.
+
+One CLI's bundled skill gives agents operating rules. The manifest gives them current state. Together they make agent work more deterministic:
+
+```bash
+one templates -o json
+one create my-app --yes -o json
+one add nextjs-app --name web --yes -o json
+```
+
+The commands are useful for humans, but the JSON envelopes and stable error codes are what make them safe for automation.
+
+## The real differentiator
+
+Most scaffolders optimize the first minute of a project. An AI-native monorepo CLI has to optimize the handoff that happens after that: a person asks an agent to add a service, fix dependencies, inspect a manifest, or prepare a workspace to run.
+
+That is where a stable CLI contract matters. It turns a monorepo from a pile of generated files into a workspace that humans, scripts, and agents can all reason about.

apps/docs/content/blog/en/coding-agent-workspace-setup.md

@@ -0,0 +1,61 @@
+---
+title: "How Coding Agents Should Prepare a Workspace to Run"
+description: "A safe workspace setup flow starts from the manifest, installs only missing dependencies, and reports exact commands."
+date: "2026-05-17"
+author: "One CLI Team"
+tags: ["agent", "dependencies", "workspace"]
+---
+
+## Start from the workspace contract
+
+When a coding agent is asked to prepare a project to run, the first step should not be a package install. The first step is finding the workspace contract. In a One CLI workspace, that contract is `one.manifest.json`.
+
+The manifest tells the agent whether it is inside a One workspace, which package manager belongs at the root, and which subprojects exist. That is safer than guessing from `apps/`, `services/`, or package scripts.
+
+## Install by toolchain, not habit
+
+The common mistake is to run one install command everywhere. That works for small single-stack projects and fails in mixed workspaces.
+
+One CLI's agent guidance separates dependency setup by toolchain:
+
+- JS, TS, and Node projects install from the workspace root with the declared package manager.
+- Go projects run module commands from the Go project directory.
+- `go mod tidy` should be used after imports change or module metadata needs repair, not as a reflex before every read-only check.
+
+This distinction keeps the agent from changing dependency files unnecessarily.
+
+## A useful setup sequence
+
+A reliable agent flow looks like this:
+
+```bash
+one templates -o json
+```
+
+Then inspect the manifest directly, choose the dependency path, and run only what is missing. For a Node workspace that uses pnpm, that usually means:
+
+```bash
+pnpm install
+```
+
+For a Go service, it usually means:
+
+```bash
+go mod download
+```
+
+The exact command should follow the workspace state, not an assumption baked into the agent prompt.
+
+## Report the commands, not just the result
+
+After setup, the agent should tell the user exactly what it ran. That makes the run reproducible and lets the user spot unnecessary actions.
+
+Good setup reports include:
+
+- The detected workspace root.
+- The package manager or Go module path used.
+- The exact install commands.
+- Any files changed by dependency repair.
+- Any command that was skipped because dependencies were already present.
+
+This is a small discipline, but it prevents a large class of hidden local-state problems.

apps/docs/content/blog/en/json-cli-contracts-for-agents.md

@@ -0,0 +1,46 @@
+---
+title: "Why CLI JSON Output Matters for Coding Agents"
+description: "Stable JSON envelopes let agents branch on error codes and context instead of parsing human help text."
+date: "2026-05-17"
+author: "One CLI Team"
+tags: ["json", "cli", "agent"]
+---
+
+## Human text is not a contract
+
+Human-friendly CLI output is useful in a terminal. It is not a good automation contract. Messages change with wording, localization, and formatting. If an agent has to parse sentences to decide what failed, the integration is fragile from the start.
+
+One CLI treats JSON output as part of the command contract. The goal is simple: agents should be able to read structured results, branch on stable fields, and report useful context back to the user.
+
+## Error codes beat message parsing
+
+The important field in a machine-readable error is the code, not the sentence. A message like "template not found" might become more helpful over time, or appear in another language. The code should stay stable.
+
+That is why agent workflows should prefer:
+
+```bash
+one templates -o json
+one create my-app --yes -o json
+one add nextjs-app --name web --yes -o json
+```
+
+If a command fails, the agent can inspect `error.code` and `error.context`. It should not scrape `error.message` for meaning.
+
+## Context reduces redundant probing
+
+A good CLI error does not only say that something failed. It returns context that helps the caller recover.
+
+For example, if a template name is wrong, the error context can include available templates. The agent can show the user valid options without running another discovery command. If a target directory exists, the context can explain the conflicting path.
+
+This makes the agent loop shorter:
+
+1. Run command with JSON output.
+2. Read stable code and context.
+3. Decide whether to recover automatically or ask the user.
+4. Report the exact reason.
+
+## JSON output is product design
+
+JSON output is often treated as an implementation detail. For agent-facing CLIs, it is product design. It defines what the agent can trust and what the user can audit.
+
+One CLI's command surface stays small, but the output contract gives it room to be used safely by scripts, CI jobs, and coding agents. That is the difference between a CLI that merely works in a terminal and a CLI that can participate in an AI-native workflow.

apps/docs/content/blog/en/monorepo-scaffold-manifest.md

@@ -0,0 +1,47 @@
+---
+title: "Why Monorepo Scaffolding Needs a Manifest"
+description: "A monorepo scaffold should record why projects exist, not just where files were generated."
+date: "2026-05-17"
+author: "One CLI Team"
+tags: ["manifest", "scaffold", "monorepo"]
+---
+
+## File layout is only the first layer
+
+Most scaffolders can create a folder layout. That is useful, but a monorepo needs more than folders. A workspace has projects, roles, dependencies, deployment targets, and conventions that should remain visible after the initial generation step.
+
+Without a manifest, later tooling has to infer intent from directory names and scripts. That might work when the repository is new, but it becomes harder as teams add services, packages, and deployment paths.
+
+## The manifest explains intent
+
+One CLI writes `one.manifest.json` so the workspace keeps a structured record of its own shape. The manifest gives future commands and agents a place to read project inventory and operational intent.
+
+That matters for common tasks:
+
+- Adding another frontend or backend with `one add`.
+- Deciding where dependencies should be installed.
+- Understanding which templates created the current projects.
+- Keeping generated guidance aligned with the workspace.
+- Letting agents inspect facts before editing files.
+
+The manifest is not a replacement for code. It is the map that tells tools how the code is organized.
+
+## Scaffolding should be reversible as knowledge
+
+The first scaffold command contains useful decisions: which template was chosen, which deploy target was selected, and which environment strategy applies. If those decisions disappear into files, every future tool has to rediscover them.
+
+A manifest keeps the decisions readable. That makes the workspace easier to automate because the next command does not have to start from zero.
+
+```bash
+one create product-suite --yes -o json
+one add nestjs-api --name api --yes -o json
+one add nextjs-app --name web --yes -o json
+```
+
+Each step should leave behind enough structure for the next step to be safer.
+
+## The agent angle
+
+Coding agents need boundaries. A manifest lets an agent answer basic questions before acting: Am I in a One workspace? Which projects exist? What is generated? Which package manager is expected?
+
+That is why manifest-driven scaffolding fits AI-native development better than one-shot folder generation. The tool does not only create files. It preserves the workspace facts that agents need later.

apps/docs/content/blog/en/one-cli-vs-general-scaffolding.md

@@ -0,0 +1,46 @@
+---
+title: "One CLI vs General Scaffolding Tools"
+description: "One CLI focuses on workspace contracts and agent-safe operations, not only initial project generation."
+date: "2026-05-17"
+author: "One CLI Team"
+tags: ["scaffolding", "comparison", "workflow"]
+---
+
+## The difference is what happens after generation
+
+General scaffolding tools are useful because they save the first setup steps. They create a starter app, write config files, and get the project to a familiar baseline. That is still valuable.
+
+One CLI is aimed at a different problem: what happens after the files exist. A team needs to add more projects, explain the workspace to agents, install dependencies safely, configure deployment targets, and keep the structure understandable over time.
+
+## General scaffolding optimizes the start
+
+Most scaffolding tools optimize for a fast beginning:
+
+- Pick a framework.
+- Generate the files.
+- Install dependencies.
+- Print a next command.
+
+That flow is enough for a single app. It becomes less complete when the repository is a monorepo or when coding agents need structured context.
+
+If later automation has to inspect folders and guess which commands are valid, the original scaffold did not leave behind enough contract.
+
+## One CLI optimizes the workspace lifecycle
+
+One CLI keeps the initial generation flow, but adds a workspace layer around it. The manifest, template registry, JSON output, and bundled skill all exist so future operations have a reliable starting point.
+
+The difference shows up in everyday tasks:
+
+- `one add` can add another project without losing workspace context.
+- `one templates -o json` gives agents a parseable template catalog.
+- Stable error codes let automation recover without parsing text.
+- The bundled skill tells agents how to install dependencies by toolchain.
+- The manifest tells tools what the workspace contains.
+
+This makes One CLI less like a one-time generator and more like a workspace contract manager.
+
+## When the distinction matters
+
+If you only need one tiny app, a general scaffolder may be enough. If you expect a workspace to involve multiple projects, agents, deployment paths, or repeated handoffs, the contract becomes more important than the first file write.
+
+One CLI is designed for that second case. It still scaffolds, but the larger purpose is to make the workspace legible to humans, scripts, and coding agents after generation.

apps/docs/content/blog/en/template-governance-for-ai-workspaces.md

@@ -0,0 +1,46 @@
+---
+title: "Template Governance for AI-Ready Workspaces"
+description: "Templates are safer for agents when they carry conventions, dependency rules, and generated guidance together."
+date: "2026-05-17"
+author: "One CLI Team"
+tags: ["templates", "governance", "agent"]
+---
+
+## Templates are policy, not only files
+
+A template is often treated as a bundle of starter files. In an AI-ready workspace, a template also carries policy: how dependencies are installed, how environment variables are documented, where generated files end, and where business code begins.
+
+If that policy is only implied by file layout, agents have to infer it. If the policy is part of the template and manifest contract, agents can check it.
+
+## Governance starts at creation time
+
+One CLI templates are meant to make the first project consistent with later operations. That means `one create` and `one add` should not only write files. They should also register enough structure for future commands to understand what was created.
+
+Good template governance answers:
+
+- What category does this project belong to?
+- Which runtime and package manager does it expect?
+- What default commands are safe to run?
+- What environment variables need user-owned values?
+- Which files are generated guidance and which are application code?
+
+These details help humans, but they are especially important for coding agents.
+
+## The agent should not invent conventions
+
+When an agent opens a generated workspace, it should not need to invent the workflow. It should read the manifest, follow the bundled skill, and use the documented commands.
+
+That means template governance has to be boring and explicit. A generated Next.js app, Go API, or documentation site should carry enough metadata for the CLI and the agent to reason about it later.
+
+```bash
+one templates -o json
+one add go-api --name api --yes -o json
+```
+
+The template name, project name, and command output become part of an auditable setup path.
+
+## Why this matters over time
+
+The value of governance grows after the repository changes hands. A new teammate or agent session can inspect the workspace and recover the original intent. That reduces onboarding friction and lowers the risk of local setup mistakes.
+
+Template governance is not about making scaffolding heavier. It is about making generated workspaces durable enough for repeated human and agent operation.

apps/docs/content/blog/zh/ai-native-monorepo-cli.md

@@ -0,0 +1,48 @@
+---
+title: "AI-Native Monorepo CLI 到底要控制什么"
+description: "AI-native monorepo CLI 不只是生成目录，而是给 agent 一个稳定的工作区契约。"
+date: "2026-05-17"
+author: "One CLI Team"
+tags: ["ai-native", "monorepo", "cli"]
+---
+
+## AI-native 是操作边界
+
+AI-native CLI 不是简单地在介绍里写上 agent。它真正要解决的是：agent 能不能在一个稳定边界里工作。关键问题不是 agent 能不能改文件，而是 agent 能不能发现 workspace 结构、知道哪些文件是生成产物、运行正确的依赖命令，并把失败结果用可解析的方式返回。
+
+对 monorepo 来说，这个边界更重要。一个仓库里可能同时有前端、后端、文档站、共享包、移动端和部署配置。如果没有共同契约，每次命令执行和 agent 接手都要重新猜。
+
+## CLI 必须显式表达哪些事实
+
+One CLI 把 workspace manifest 当作共同契约。生成的项目、模板来源、包管理器选择和运行意图，都应该来自结构化数据，而不是散落在 README 文案里。
+
+一个 AI-native monorepo CLI 至少要显式表达这些事实：
+
+- workspace root 在哪里。
+- 哪些项目是 app、service、package 或 docs。
+- 每个项目来自哪个模板。
+- 每个项目应该用哪类依赖工具链。
+- 哪些命令可以自动运行。
+- 哪些错误有稳定的机器可读 code。
+
+这也是为什么 `one create`、`one add`、`one templates` 和 JSON 输出属于同一个产品面。脚手架负责开始项目，但契约负责让项目在第一次生成之后仍然可维护。
+
+## agent 需要的不只是 README
+
+人可以读 README，再对照文件树推断缺失信息。agent 也可以这样做，但更慢，也更不稳定。如果 agent 要判断是在根目录运行 `pnpm install`，还是进某个服务里运行 `go mod download`，只靠目录名猜是不够的。
+
+One CLI 的 bundled skill 给 agent 操作规则，manifest 给 agent 当前状态。两者配合后，agent 工作会更确定：
+
+```bash
+one templates -o json
+one create my-app --yes -o json
+one add nextjs-app --name web --yes -o json
+```
+
+这些命令对人也有用，但真正适合自动化的是 JSON envelope 和稳定 error code。
+
+## 真正的差异点
+
+大多数脚手架优化的是项目开始的第一分钟。AI-native monorepo CLI 要优化的是之后的交接：人让 agent 加服务、补依赖、检查 manifest，或者准备 workspace 运行。
+
+稳定的 CLI 契约就在这里产生价值。它让 monorepo 不再只是一堆生成出来的文件，而是人、脚本和 agent 都能理解的工作区。