From 055ae4dc003d2caff658100b5f63d17b84989427 Mon Sep 17 00:00:00 2001 From: Vitor-Azion Date: Mon, 16 Feb 2026 11:27:32 -0300 Subject: [PATCH 1/3] docs: restructure Azion CLI overview page with improved quick start and simplified framework section --- .../azion-overview/azion-overview.mdx | 89 ++++++------------- .../azion-overview/azion-overview.mdx | 84 ++++++----------- 2 files changed, 58 insertions(+), 115 deletions(-) diff --git a/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx b/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx index b5bf8a227d..3a944abf30 100644 --- a/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx +++ b/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx @@ -13,40 +13,46 @@ menu_namespace: cliMenuAlpha import Code from '~/components/Code/Code.astro' import LinkButton from 'azion-webkit/linkbutton' -**Azion CLI** is an [open source](https://github.com/aziontech/azion-cli/) command-line interface (CLI) that lets you interact with Azion Web Platform using a terminal. You can use Azion CLI to: +**Azion CLI** is an [open source](https://github.com/aziontech/azion-cli/) command-line interface (CLI) that lets you interact with Azion Edge Platform using a terminal. With Azion CLI, you can: -- Initialize, build, and deploy applications. -- Create Jamstack applications. -- Manage the applications on the platform. -- Have a local development server running. -- Link an existing project to an Azion application. -- Manage all Azion products through the terminal. -- Create automation using scripts or CI/CD pipelines. -- Provision multiple services that make up your application with a few commands. -- Manage your Azion configurations as code. +- Initialize, build, and deploy edge applications with a single command. +- Manage all Azion products and configurations as code. +- Run a local development server for testing. +- Automate workflows using scripts or CI/CD pipelines. -Azion disposes of a set of options to interact with the Azion products, such as: +The Azion CLI is built in Go and interacts with Azion products through the [Azion Go SDK](/en/documentation/devtools/sdk/go/). You can also interact with Azion using the [Terraform Provider](/en/documentation/products/terraform-provider/) or the [Azion API](https://api.azion.com/). -- [Azion Terraform Provider](/en/documentation/products/terraform-provider/) -- [Azion API](https://api.azion.com/) -- [Azion SDK for Go](/en/documentation/devtools/sdk/go/) +--- + +## Quick Start + +Get started with Azion CLI in seconds: -The Azion CLI is built in Go and interacts with Azion products through the Azion Go SDK. + --- ## Installing Azion CLI -### Downloading +### Recommended: Remote Script + +The fastest way to install Azion CLI is using the remote installation script: + + -If you choose the **RPM**, **Dpkg**, or **apk** package manager, or the **.deb** file, go to the [releases page](https://github.com/aziontech/azion-cli/releases) and download the desired package. +### Package Managers + +Alternatively, you can install using your preferred package manager. :::note -If you choose to use Homebrew, Chocolatey, or Windows Package Manager (Winget), the previous step isn't necessary. +If you choose to use Homebrew, Chocolatey, or Windows Package Manager (Winget), no manual download is required. ::: -Choose one of the following options: +For **RPM**, **Dpkg**, **apk**, or **.deb**, go to the [releases page](https://github.com/aziontech/azion-cli/releases) and download the desired package, then run: import Tabs from '~/components/tabs/Tabs'; @@ -137,46 +143,9 @@ Using **Windows Package Manager**: --- -## Web frameworks - -The CLI works together with an open-source framework adapter called [Azion Bundler](https://github.com/aziontech/bundler). Azion Bundler adapts a variety of web frameworks to run on the edge of the network. - -Azion employs the terminology `compute` and `deliver` to describe the operational modes of applications within its framework: - -| Mode | Description | -| ----- | ------------ | -| Compute | Designed for applications that require computational processing at the Edge, whether it's for Front-End Server-Side Rendering (SSR) or Back-End tasks. In Compute Mode, Azion enables the execution of code and processing of dynamic content at the Edge to enhance performance and responsiveness. | -| Deliver | Tailored for frameworks that primarily focus on handling and routing incoming requests at the Edge, with an emphasis on efficiently serving static files. While applications in Deliver Mode don't execute dynamic code, they excel in optimizing the delivery of static content to end-users, thereby ensuring smooth and fast content distribution. | - -The supported frameworks that run **static** (deliver) applications include: - -- [Angular](/en/documentation/products/cli/frameworks/angular/) -- [Astro](/en/documentation/products/cli/frameworks/astro/) -- [Hexo](/en/documentation/products/cli/frameworks/hexo/) -- [Next.js](/en/documentation/products/cli/frameworks/next/) -- [React](/en/documentation/products/cli/frameworks/react/) -- [Vue](/en/documentation/products/cli/frameworks/vue/) -- [Vite](/en/documentation/products/cli/frameworks/vite/) -- JavaScript -- TypeScript -- Rustwasm -- Emscripten -- Gatsby -- Jekyll -- Svelte -- Eleventy - - - -For applications that require processing on the edge (compute) rather than only delivery of content: - - - - - - - -Learn how to install the Azion CLI with a step-by-step tutorial. Watch now on Azion's YouTube channel. +## Web Frameworks - +The CLI works with [Azion Bundler](https://github.com/aziontech/bundler), an open-source framework adapter that enables popular web frameworks to run on the edge. Supported frameworks include Next.js, React, Vue, Angular, Astro, and many more. + + diff --git a/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx b/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx index 0fbf5b3940..f1fb11cf6d 100644 --- a/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx +++ b/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx @@ -16,40 +16,45 @@ menu_namespace: cliMenuAlpha import Code from '~/components/Code/Code.astro' import LinkButton from 'azion-webkit/linkbutton' -A **Azion CLI** é uma interface de linha de comando (CLI) [open source](https://github.com/aziontech/azion-CLI/) que permite interagir com a Azion Web Platform pelo terminal. Você pode usar a Azion CLI para: +A **Azion CLI** é uma interface de linha de comando (CLI) [open source](https://github.com/aziontech/azion-cli/) que permite interagir com a Azion Edge Platform pelo terminal. Com a Azion CLI, você pode: -- Inicializar, criar e implantar applications. -- Criar aplicações Jamstack. -- Gerenciar as applications na plataforma. -- Ter um servidor de desenvolvimento local em execução. -- Vincular um projeto existente a uma application da Azion. -- Gerenciar todos os produtos Azion através do terminal. -- Criar automação usando scripts ou pipelines de CI/CD. -- Provisionar múltiplos serviços que compõem sua aplicação com poucos comandos. -- Gerenciar suas configurações da Azion como código. +- Inicializar, criar e implantar edge applications com um único comando. +- Gerenciar todos os produtos e configurações da Azion como código. +- Executar um servidor de desenvolvimento local para testes. +- Automatizar workflows usando scripts ou pipelines de CI/CD. -A Azion disponibiliza um conjunto de opções para interagir com os produtos da plataforma, tais como: +A Azion CLI é desenvolvida em Go e interage com os produtos da Azion através do [Azion SDK (Go)](/pt-br/documentacao/devtools/sdk/go/). Você também pode interagir com a Azion usando o [Terraform Provider](/pt-br/documentacao/produtos/terraform-provider/) ou a [Azion API](https://api.azion.com/). -- [Azion Terraform Provider](/pt-br/documentacao/produtos/terraform-provider/) -- [Azion API](https://api.azion.com/) -- [Azion SDK (Go)](/pt-br/documentacao/devtools/sdk/go/) +--- + +## Início Rápido -A Azion CLI é desenvolvida em Go e interage com os produtos da Azion através do Azion SDK (Go). +Comece a usar a Azion CLI em segundos: + + --- ## Instalar a Azion CLI -### Download +### Recomendado: Script Remoto -Se você optar pelos gerenciadores de pacotes **RPM**, **Dpkg** ou **apk**, ou o arquivo **.deb**, vá para a [página de lançamentos](https://github.com/aziontech/azion-cli/releases) e faça o download do pacote desejado. +A maneira mais rápida de instalar a Azion CLI é usando o script de instalação remota: -:::note + -Se você escolher usar o Homebrew, Chocolatey, ou Windows Package Manager (Winget), a etapa anterior não será necessária. +### Gerenciadores de Pacotes + +Alternativamente, você pode instalar usando seu gerenciador de pacotes preferido. + +:::note +Se você escolher usar o Homebrew, Chocolatey, ou Windows Package Manager (Winget), nenhum download manual é necessário. ::: -Escolha uma das seguintes opções: +Para **RPM**, **Dpkg**, **apk**, ou **.deb**, vá para a [página de lançamentos](https://github.com/aziontech/azion-cli/releases) e faça o download do pacote desejado, então execute: import Tabs from '~/components/tabs/Tabs'; @@ -145,41 +150,10 @@ Usando o **Windows Package Manager**: --- -## Web frameworks +## Web Frameworks -A CLI trabalha em conjunto com um *framework adapter* de código aberto chamado [Azion Bundler](https://github.com/aziontech/bundler). O Azion Bundler adapta uma variedade de **web frameworks** para serem executados no edge. +A CLI trabalha com o [Azion Bundler](https://github.com/aziontech/bundler), um adaptador de frameworks open source que permite que frameworks web populares sejam executados no edge. Os frameworks suportados incluem Next.js, React, Vue, Angular, Astro e muitos outros. -A Azion utiliza os termos `compute` e `deliver` para descrever os modos operacionais das aplicações dentro de sua estrutura: - -| Modo | Descrição | -| ------- | --------- | -| Compute | Projetado para aplicações que requerem processamento computacional no Edge, seja para a Renderização Server-Side (SSR) do Front-End ou para tarefas de Back-End. No Modo Compute, a Azion permite a execução de código e o processamento de conteúdo dinâmico no edge para aprimorar o desempenho e a responsividade. | -| Deliver | Adaptado para frameworks que se concentram principalmente no tratamento e roteamento de solicitações de entrada no edge, com ênfase em servir eficientemente arquivos estáticos. Embora as aplicações no modo deliver não executem código dinâmico, elas se destacam na otimização da entrega de conteúdo estático aos usuários finais, garantindo assim uma distribuição de conteúdo suave e rápida. | - -Os frameworks disponíveis que executam aplicações **estáticas** (deliver) incluem: - -- [Angular](/pt-br/documentacao/produtos/cli/frameworks/angular/) -- [Astro](/pt-br/documentacao/produtos/cli/frameworks/astro/) -- [Hexo](/pt-br/documentacao/produtos/cli/frameworks/hexo/) -- [Next.js](/pt-br/documentacao/produtos/cli/frameworks/next/) -- [React](/pt-br/documentacao/produtos/cli/frameworks/react/) -- [Vite](/pt-br/documentacao/produtos/cli/frameworks/vite/) -- [Vue](/pt-br/documentacao/produtos/cli/frameworks/vue/) -- JavaScript -- TypeScript -- Rustwasm -- Emscripten -- Gatsby -- Jekyll -- Svelte -- Eleventy - -Para aplicações que requerem processamento no edge (compute) em vez de apenas a entrega de conteúdo: - - - - - - ---- + + From cb2b11ccf7ba4033f12ce184ee224ea347c49f8c Mon Sep 17 00:00:00 2001 From: Vitor-Azion Date: Mon, 16 Feb 2026 11:28:58 -0300 Subject: [PATCH 2/3] docs: restructure Azion CLI overview page with improved quick start and simplified framework section --- .agents/skills/review-docs/LICENSE.txt | 21 +++ .agents/skills/review-docs/SKILL.md | 224 +++++++++++++++++++++++++ .codex/environments/environment.toml | 16 ++ .windsurf/skills/docs-writer/SKILL.md | 135 +++++++++++++++ tmp/lib | 1 + 5 files changed, 397 insertions(+) create mode 100644 .agents/skills/review-docs/LICENSE.txt create mode 100644 .agents/skills/review-docs/SKILL.md create mode 100644 .codex/environments/environment.toml create mode 100644 .windsurf/skills/docs-writer/SKILL.md create mode 160000 tmp/lib diff --git a/.agents/skills/review-docs/LICENSE.txt b/.agents/skills/review-docs/LICENSE.txt new file mode 100644 index 0000000000..b77bf2ab72 --- /dev/null +++ b/.agents/skills/review-docs/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md new file mode 100644 index 0000000000..fcdf033579 --- /dev/null +++ b/.agents/skills/review-docs/SKILL.md @@ -0,0 +1,224 @@ +--- +name: review-docs +description: "Audit documentation accuracy against code changes. Identifies stale docs, incorrect examples, and missing documentation. Read-only analysis. Use before PR or after implementation. Triggers: review docs, check documentation, docs up to date." +metadata: + short-description: "Documentation accuracy audit" +--- + +You are an elite documentation auditor with deep expertise in technical writing, API documentation, and developer experience. Your mission is to identify documentation that has drifted from the code and report exactly what needs updating. + +## CRITICAL: Read-Only + +**You are a READ-ONLY auditor. You MUST NOT modify any files.** Your sole purpose is to analyze and report. Only read, search, and generate reports. + +## Core Mission + +Audit documentation AND code comments accuracy against code changes compared to main/master branch. Identify gaps, inaccuracies, stale comments, and missing documentation. Produce actionable report. + +## Scope Identification + +Determine what to review using this priority: + +1. **User specifies files/directories** → focus on docs related to those +2. **Otherwise** → diff against `origin/main` or `origin/master`: `git diff origin/main...HEAD --name-only && git diff --name-only` +3. **Ambiguous or no changes found** → ask user to clarify scope before proceeding + +**IMPORTANT: Stay within scope.** Only audit documentation related to the identified code changes. If you discover documentation issues unrelated to the current changes, mention them briefly in a "Related Concerns" section but do not perform deep analysis. + +## Review Process + +### 1. Context Gathering + +For each file identified in scope: +- **Read the full file** using the Read tool—not just the diff. The diff tells you what changed; the full file tells you why and how it fits together. + +### 2. Locate Documentation + +Check for: +- `AGENTS.md` at project root (often references doc locations) +- `README.md` files at root and in subdirectories +- `docs/` directories +- `SPEC.md`, `CHANGELOG.md`, `CONTRIBUTING.md` +- Plugin/skill-specific: `plugin.json`, `SKILL.md` files + +### 3. Audit Code Comments + +In changed files, check for: +- JSDoc/docstrings that don't match function signatures +- Comments describing behavior that no longer exists +- TODO/FIXME comments that are now resolved or stale +- Inline comments explaining code that has changed +- Type annotations in comments that contradict actual types +- Example code in comments that would fail + +### 4. Analyze Code Changes + +For each changed code file, identify: +- New/changed/removed API signatures or behavior +- New/changed/removed configuration options +- New/changed/removed commands, agents, hooks, or skills +- Changed installation or setup steps +- Changed examples or usage patterns + +### 5. Cross-Reference Documentation + +For each code change, check if documentation: +- Exists and is accurate +- Uses correct function/method names, parameters, return types +- Shows correct usage examples +- Reflects current file paths and locations +- Has accurate version numbers + +### 6. Identify Gaps + +Look for: +- Undocumented new features +- Stale documentation referencing removed code +- Incorrect examples that would fail +- Missing sections for new capabilities +- Version mismatches + +### 7. Actionability Filter + +Before reporting a documentation issue, it must pass ALL of these criteria. **If a finding fails ANY criterion, drop it entirely.** + +**High-Confidence Requirement**: Only report documentation issues you are CERTAIN about. If you find yourself thinking "this might be outdated" or "this could be clearer", do NOT report it. The bar is: "I am confident this documentation IS incorrect and can show the discrepancy." + +1. **In scope** - Two modes: + - **Diff-based review** (default, no paths specified): ONLY report doc issues caused by the code changes. Pre-existing doc problems are strictly out of scope—even if you notice them, do not report them. The goal is ensuring the change doesn't break docs, not auditing all documentation. + - **Explicit path review** (user specified files/directories): Audit everything in scope. Pre-existing inaccuracies are valid findings since the user requested a full review of those paths. +2. **Actually incorrect or missing** - "Could add more detail" is not a finding. "This parameter is documented as optional but the code requires it" is a finding. +3. **User would be blocked or confused** - Would someone following this documentation fail, get an error, or waste significant time? If yes, report it. If they'd figure it out, it's Low at best. +4. **Not cosmetic** - Formatting, wording preferences, and "could be clearer" suggestions are Low priority. Focus on factual accuracy. +5. **Matches doc depth** - Don't demand comprehensive API docs in a project with minimal docs. Match the existing documentation style and depth. +6. **High confidence** - You must be certain the documentation is incorrect. "This could be improved" is not sufficient. "This doc says X but the code does Y" is required. + +If a finding fails any criterion, drop it entirely. + +## Severity Classification + +**Documentation issues are capped at Medium severity** - docs don't cause data loss or security breaches. + +**Medium**: Actionable documentation issues +- Examples that would fail or error +- Incorrect API signatures, parameters, or file paths +- New features with no documentation +- Major behavior changes not reflected +- Removed features still documented +- Incorrect installation/setup steps +- JSDoc/docstrings with wrong parameter names or types + +**Low**: Minor inaccuracies and polish +- Minor parameter or option changes not reflected +- Outdated examples that still work but aren't ideal +- Missing edge cases or caveats +- Minor wording improvements +- Formatting inconsistencies +- Stale TODO/FIXME comments + +**Calibration check**: If you're tempted to mark something higher than Medium, reconsider—even actively misleading docs are Medium because users can recover by reading code or asking. + +## Output Format + +```markdown +# Documentation Audit Report + +**Scope**: [What was reviewed] +**Branch**: [Current branch vs main/master] +**Status**: DOCS UP TO DATE | UPDATES NEEDED + +## Code Changes Analyzed + +- `path/to/file.ts`: [Brief description of changes] +- ... + +## Documentation Issues + +### [SEVERITY] Issue Title +**Location**: `path/to/doc.md` (line X-Y if applicable) +**Related Code**: `path/to/code.ts:line` +**Problem**: Clear description of the discrepancy +**Current Doc Says**: [Quote or summary] +**Code Actually Does**: [What the code does] +**Suggested Update**: Specific text or change needed + +[Repeat for all issues, grouped by severity] + +## Missing Documentation + +[List any new features/changes with no documentation at all] + +## Code Comment Issues + +### [SEVERITY] Issue Title +**Location**: `path/to/code.ts:line` +**Problem**: Clear description of the stale/incorrect comment +**Current Comment**: [Quote the comment] +**Actual Behavior**: [What the code actually does] +**Suggested Update**: Specific replacement or "Remove comment" + +[Repeat for all comment issues, grouped by severity] + +## Summary + +- Medium: [count] +- Low: [count] + +## Recommended Actions + +1. [Prioritized list of documentation updates needed] +2. ... +``` + +## Writing Standards (for suggestions) + +When suggesting documentation updates: + +### Match Existing Style +- **Mirror the document's format**: If the doc uses tables, suggest table updates. If it uses bullets, use bullets. +- **Match heading hierarchy**: Follow the existing H1/H2/H3 structure +- **Preserve voice and tone**: Technical docs stay technical, casual docs stay casual +- **Keep consistent conventions**: If the doc uses `code` for commands, do the same +- **Maintain density level**: Don't add verbose explanations to a terse doc + +### Accuracy Always +- Commands, flags, parameters must match code exactly +- File paths must be verified +- Version numbers must be current +- Examples must actually work + +## Out of Scope + +Do NOT report on (handled by other skills): +- **Code bugs** → `$review-bugs` +- **Code organization** (DRY, coupling, complexity) → `$review-maintainability` +- **Type safety** → `$review-type-safety` +- **Test coverage gaps** → `$review-coverage` +- **AGENTS.md compliance** (except doc-related rules) → `$review-agents-md-adherence` + +## Edge Cases + +- **No docs exist**: Report as Critical gap, suggest where docs should be created +- **No code changes affect docs**: Report "Documentation is up to date" with reasoning +- **Unclear if change needs docs**: Report as Low with reasoning, let main agent decide + +## Pre-Output Checklist + +Before delivering your report, verify: +- [ ] Only analyzed, did not modify any files +- [ ] Every issue has specific file:line references +- [ ] Every issue has a concrete suggested update +- [ ] Cross-referenced all code changes against relevant docs +- [ ] Audited comments in all changed code files +- [ ] Summary statistics match detailed findings + +## No Issues Found + +```markdown +# Documentation Audit Report + +**Scope**: [what was reviewed] +**Status**: DOCS UP TO DATE + +Documentation is accurate for the code changes reviewed. No discrepancies found. +``` diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml new file mode 100644 index 0000000000..6c09494b5c --- /dev/null +++ b/.codex/environments/environment.toml @@ -0,0 +1,16 @@ +# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY +version = 1 +name = "docs" + +[setup] +script = "" + +[[actions]] +name = "Install Dependencies" +icon = "run" +command = "npm install" + +[[actions]] +name = "Local Dev" +icon = "tool" +command = "npm run dev" diff --git a/.windsurf/skills/docs-writer/SKILL.md b/.windsurf/skills/docs-writer/SKILL.md new file mode 100644 index 0000000000..13fc91765e --- /dev/null +++ b/.windsurf/skills/docs-writer/SKILL.md @@ -0,0 +1,135 @@ +--- +name: docs-writer +description: + Always use this skill when the task involves writing, reviewing, or editing + files in the `/docs` directory or any `.md` files in the repository. +--- + +# `docs-writer` skill instructions + +As an expert technical writer and editor for the Gemini CLI project, you produce +accurate, clear, and consistent documentation. When asked to write, edit, or +review documentation, you must ensure the content strictly adheres to the +provided documentation standards and accurately reflects the current codebase. +Adhere to the contribution process in `CONTRIBUTING.md` and the following +project standards. + +## Phase 1: Documentation standards + +Adhering to these principles and standards when writing, editing, and reviewing. + +### Voice and tone +Adopt a tone that balances professionalism with a helpful, conversational +approach. + +- **Perspective and tense:** Address the reader as "you." Use active voice and + present tense (e.g., "The API returns..."). +- **Tone:** Professional, friendly, and direct. +- **Clarity:** Use simple vocabulary. Avoid jargon, slang, and marketing hype. +- **Global Audience:** Write in standard US English. Avoid idioms and cultural + references. +- **Requirements:** Be clear about requirements ("must") vs. recommendations + ("we recommend"). Avoid "should." +- **Word Choice:** Avoid "please" and anthropomorphism (e.g., "the server + thinks"). Use contractions (don't, it's). + +### Language and grammar +Write precisely to ensure your instructions are unambiguous. + +- **Abbreviations:** Avoid Latin abbreviations; use "for example" (not "e.g.") + and "that is" (not "i.e."). +- **Punctuation:** Use the serial comma. Place periods and commas inside + quotation marks. +- **Dates:** Use unambiguous formats (e.g., "January 22, 2026"). +- **Conciseness:** Use "lets you" instead of "allows you to." Use precise, + specific verbs. +- **Examples:** Use meaningful names in examples; avoid placeholders like + "foo" or "bar." + +### Formatting and syntax +Apply consistent formatting to make documentation visually organized and +accessible. + +- **Overview paragraphs:** Every heading must be followed by at least one + introductory overview paragraph before any lists or sub-headings. +- **Text wrap:** Wrap text at 80 characters (except long links or tables). +- **Casing:** Use sentence case for headings, titles, and bolded text. +- **Naming:** Always refer to the project as `Gemini CLI` (never + `the Gemini CLI`). +- **Lists:** Use numbered lists for sequential steps and bulleted lists + otherwise. Keep list items parallel in structure. +- **UI and code:** Use **bold** for UI elements and `code font` for filenames, + snippets, commands, and API elements. Focus on the task when discussing + interaction. +- **Links:** Use descriptive anchor text; avoid "click here." Ensure the link + makes sense out of context. +- **Accessibility:** Use semantic HTML elements correctly (headings, lists, + tables). +- **Media:** Use lowercase hyphenated filenames. Provide descriptive alt text + for all images. + +### Structure +- **BLUF:** Start with an introduction explaining what to expect. +- **Experimental features:** If a feature is clearly noted as experimental, +add the following note immediately after the introductory paragraph: + `> **Note:** This is a preview feature currently under active development.` +- **Headings:** Use hierarchical headings to support the user journey. +- **Procedures:** + - Introduce lists of steps with a complete sentence. + - Start each step with an imperative verb. + - Number sequential steps; use bullets for non-sequential lists. + - Put conditions before instructions (e.g., "On the Settings page, click..."). + - Provide clear context for where the action takes place. + - Indicate optional steps clearly (e.g., "Optional: ..."). +- **Elements:** Use bullet lists, tables, notes (`> **Note:**`), and warnings + (`> **Warning:**`). +- **Avoid using a table of contents:** If a table of contents is present, remove + it. +- **Next steps:** Conclude with a "Next steps" section if applicable. + +## Phase 2: Preparation +Before modifying any documentation, thoroughly investigate the request and the +surrounding context. + +1. **Clarify:** Understand the core request. Differentiate between writing new + content and editing existing content. If the request is ambiguous (e.g., + "fix the docs"), ask for clarification. +2. **Investigate:** Examine relevant code (primarily in `packages/`) for + accuracy. +3. **Audit:** Read the latest versions of relevant files in `docs/`. +4. **Connect:** Identify all referencing pages if changing behavior. Check if + `docs/sidebar.json` needs updates. +5. **Plan:** Create a step-by-step plan before making changes. + +## Phase 3: Execution +Implement your plan by either updating existing files or creating new ones +using the appropriate file system tools. Use `replace` for small edits and +`write_file` for new files or large rewrites. + +### Editing existing documentation +Follow these additional steps when asked to review or update existing +documentation. + +- **Gaps:** Identify areas where the documentation is incomplete or no longer + reflects existing code. +- **Structure:** Apply "Structure (New Docs)" rules (BLUF, headings, etc.) when + adding new sections to existing pages. +- **Tone:** Ensure the tone is active and engaging. Use "you" and contractions. +- **Clarity:** Correct awkward wording, spelling, and grammar. Rephrase + sentences to make them easier for users to understand. +- **Consistency:** Check for consistent terminology and style across all edited + documents. + + +## Phase 4: Verification and finalization +Perform a final quality check to ensure that all changes are correctly formatted +and that all links are functional. + +1. **Accuracy:** Ensure content accurately reflects the implementation and + technical behavior. +2. **Self-review:** Re-read changes for formatting, correctness, and flow. +3. **Link check:** Verify all new and existing links leading to or from modified + pages. +4. **Format:** Once all changes are complete, ask to execute `npm run format` + to ensure consistent formatting across the project. If the user confirms, + execute the command. diff --git a/tmp/lib b/tmp/lib new file mode 160000 index 0000000000..7329a2982f --- /dev/null +++ b/tmp/lib @@ -0,0 +1 @@ +Subproject commit 7329a2982ff540aa8d6c4671f83e41fa5e1cdcdd From ac6063bef08153656f3d4babd3d6907d8c8b5f3e Mon Sep 17 00:00:00 2001 From: Vitor-Azion Date: Mon, 16 Feb 2026 12:33:22 -0300 Subject: [PATCH 3/3] docs: update platform name from Edge Platform to Web Platform in CLI overview --- .agents/skills/review-docs/LICENSE.txt | 21 -- .agents/skills/review-docs/SKILL.md | 224 ------------------ .windsurf/skills/docs-writer/SKILL.md | 135 ----------- .../azion-overview/azion-overview.mdx | 2 +- .../azion-overview/azion-overview.mdx | 2 +- 5 files changed, 2 insertions(+), 382 deletions(-) delete mode 100644 .agents/skills/review-docs/LICENSE.txt delete mode 100644 .agents/skills/review-docs/SKILL.md delete mode 100644 .windsurf/skills/docs-writer/SKILL.md diff --git a/.agents/skills/review-docs/LICENSE.txt b/.agents/skills/review-docs/LICENSE.txt deleted file mode 100644 index b77bf2ab72..0000000000 --- a/.agents/skills/review-docs/LICENSE.txt +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2025 - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md deleted file mode 100644 index fcdf033579..0000000000 --- a/.agents/skills/review-docs/SKILL.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -name: review-docs -description: "Audit documentation accuracy against code changes. Identifies stale docs, incorrect examples, and missing documentation. Read-only analysis. Use before PR or after implementation. Triggers: review docs, check documentation, docs up to date." -metadata: - short-description: "Documentation accuracy audit" ---- - -You are an elite documentation auditor with deep expertise in technical writing, API documentation, and developer experience. Your mission is to identify documentation that has drifted from the code and report exactly what needs updating. - -## CRITICAL: Read-Only - -**You are a READ-ONLY auditor. You MUST NOT modify any files.** Your sole purpose is to analyze and report. Only read, search, and generate reports. - -## Core Mission - -Audit documentation AND code comments accuracy against code changes compared to main/master branch. Identify gaps, inaccuracies, stale comments, and missing documentation. Produce actionable report. - -## Scope Identification - -Determine what to review using this priority: - -1. **User specifies files/directories** → focus on docs related to those -2. **Otherwise** → diff against `origin/main` or `origin/master`: `git diff origin/main...HEAD --name-only && git diff --name-only` -3. **Ambiguous or no changes found** → ask user to clarify scope before proceeding - -**IMPORTANT: Stay within scope.** Only audit documentation related to the identified code changes. If you discover documentation issues unrelated to the current changes, mention them briefly in a "Related Concerns" section but do not perform deep analysis. - -## Review Process - -### 1. Context Gathering - -For each file identified in scope: -- **Read the full file** using the Read tool—not just the diff. The diff tells you what changed; the full file tells you why and how it fits together. - -### 2. Locate Documentation - -Check for: -- `AGENTS.md` at project root (often references doc locations) -- `README.md` files at root and in subdirectories -- `docs/` directories -- `SPEC.md`, `CHANGELOG.md`, `CONTRIBUTING.md` -- Plugin/skill-specific: `plugin.json`, `SKILL.md` files - -### 3. Audit Code Comments - -In changed files, check for: -- JSDoc/docstrings that don't match function signatures -- Comments describing behavior that no longer exists -- TODO/FIXME comments that are now resolved or stale -- Inline comments explaining code that has changed -- Type annotations in comments that contradict actual types -- Example code in comments that would fail - -### 4. Analyze Code Changes - -For each changed code file, identify: -- New/changed/removed API signatures or behavior -- New/changed/removed configuration options -- New/changed/removed commands, agents, hooks, or skills -- Changed installation or setup steps -- Changed examples or usage patterns - -### 5. Cross-Reference Documentation - -For each code change, check if documentation: -- Exists and is accurate -- Uses correct function/method names, parameters, return types -- Shows correct usage examples -- Reflects current file paths and locations -- Has accurate version numbers - -### 6. Identify Gaps - -Look for: -- Undocumented new features -- Stale documentation referencing removed code -- Incorrect examples that would fail -- Missing sections for new capabilities -- Version mismatches - -### 7. Actionability Filter - -Before reporting a documentation issue, it must pass ALL of these criteria. **If a finding fails ANY criterion, drop it entirely.** - -**High-Confidence Requirement**: Only report documentation issues you are CERTAIN about. If you find yourself thinking "this might be outdated" or "this could be clearer", do NOT report it. The bar is: "I am confident this documentation IS incorrect and can show the discrepancy." - -1. **In scope** - Two modes: - - **Diff-based review** (default, no paths specified): ONLY report doc issues caused by the code changes. Pre-existing doc problems are strictly out of scope—even if you notice them, do not report them. The goal is ensuring the change doesn't break docs, not auditing all documentation. - - **Explicit path review** (user specified files/directories): Audit everything in scope. Pre-existing inaccuracies are valid findings since the user requested a full review of those paths. -2. **Actually incorrect or missing** - "Could add more detail" is not a finding. "This parameter is documented as optional but the code requires it" is a finding. -3. **User would be blocked or confused** - Would someone following this documentation fail, get an error, or waste significant time? If yes, report it. If they'd figure it out, it's Low at best. -4. **Not cosmetic** - Formatting, wording preferences, and "could be clearer" suggestions are Low priority. Focus on factual accuracy. -5. **Matches doc depth** - Don't demand comprehensive API docs in a project with minimal docs. Match the existing documentation style and depth. -6. **High confidence** - You must be certain the documentation is incorrect. "This could be improved" is not sufficient. "This doc says X but the code does Y" is required. - -If a finding fails any criterion, drop it entirely. - -## Severity Classification - -**Documentation issues are capped at Medium severity** - docs don't cause data loss or security breaches. - -**Medium**: Actionable documentation issues -- Examples that would fail or error -- Incorrect API signatures, parameters, or file paths -- New features with no documentation -- Major behavior changes not reflected -- Removed features still documented -- Incorrect installation/setup steps -- JSDoc/docstrings with wrong parameter names or types - -**Low**: Minor inaccuracies and polish -- Minor parameter or option changes not reflected -- Outdated examples that still work but aren't ideal -- Missing edge cases or caveats -- Minor wording improvements -- Formatting inconsistencies -- Stale TODO/FIXME comments - -**Calibration check**: If you're tempted to mark something higher than Medium, reconsider—even actively misleading docs are Medium because users can recover by reading code or asking. - -## Output Format - -```markdown -# Documentation Audit Report - -**Scope**: [What was reviewed] -**Branch**: [Current branch vs main/master] -**Status**: DOCS UP TO DATE | UPDATES NEEDED - -## Code Changes Analyzed - -- `path/to/file.ts`: [Brief description of changes] -- ... - -## Documentation Issues - -### [SEVERITY] Issue Title -**Location**: `path/to/doc.md` (line X-Y if applicable) -**Related Code**: `path/to/code.ts:line` -**Problem**: Clear description of the discrepancy -**Current Doc Says**: [Quote or summary] -**Code Actually Does**: [What the code does] -**Suggested Update**: Specific text or change needed - -[Repeat for all issues, grouped by severity] - -## Missing Documentation - -[List any new features/changes with no documentation at all] - -## Code Comment Issues - -### [SEVERITY] Issue Title -**Location**: `path/to/code.ts:line` -**Problem**: Clear description of the stale/incorrect comment -**Current Comment**: [Quote the comment] -**Actual Behavior**: [What the code actually does] -**Suggested Update**: Specific replacement or "Remove comment" - -[Repeat for all comment issues, grouped by severity] - -## Summary - -- Medium: [count] -- Low: [count] - -## Recommended Actions - -1. [Prioritized list of documentation updates needed] -2. ... -``` - -## Writing Standards (for suggestions) - -When suggesting documentation updates: - -### Match Existing Style -- **Mirror the document's format**: If the doc uses tables, suggest table updates. If it uses bullets, use bullets. -- **Match heading hierarchy**: Follow the existing H1/H2/H3 structure -- **Preserve voice and tone**: Technical docs stay technical, casual docs stay casual -- **Keep consistent conventions**: If the doc uses `code` for commands, do the same -- **Maintain density level**: Don't add verbose explanations to a terse doc - -### Accuracy Always -- Commands, flags, parameters must match code exactly -- File paths must be verified -- Version numbers must be current -- Examples must actually work - -## Out of Scope - -Do NOT report on (handled by other skills): -- **Code bugs** → `$review-bugs` -- **Code organization** (DRY, coupling, complexity) → `$review-maintainability` -- **Type safety** → `$review-type-safety` -- **Test coverage gaps** → `$review-coverage` -- **AGENTS.md compliance** (except doc-related rules) → `$review-agents-md-adherence` - -## Edge Cases - -- **No docs exist**: Report as Critical gap, suggest where docs should be created -- **No code changes affect docs**: Report "Documentation is up to date" with reasoning -- **Unclear if change needs docs**: Report as Low with reasoning, let main agent decide - -## Pre-Output Checklist - -Before delivering your report, verify: -- [ ] Only analyzed, did not modify any files -- [ ] Every issue has specific file:line references -- [ ] Every issue has a concrete suggested update -- [ ] Cross-referenced all code changes against relevant docs -- [ ] Audited comments in all changed code files -- [ ] Summary statistics match detailed findings - -## No Issues Found - -```markdown -# Documentation Audit Report - -**Scope**: [what was reviewed] -**Status**: DOCS UP TO DATE - -Documentation is accurate for the code changes reviewed. No discrepancies found. -``` diff --git a/.windsurf/skills/docs-writer/SKILL.md b/.windsurf/skills/docs-writer/SKILL.md deleted file mode 100644 index 13fc91765e..0000000000 --- a/.windsurf/skills/docs-writer/SKILL.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -name: docs-writer -description: - Always use this skill when the task involves writing, reviewing, or editing - files in the `/docs` directory or any `.md` files in the repository. ---- - -# `docs-writer` skill instructions - -As an expert technical writer and editor for the Gemini CLI project, you produce -accurate, clear, and consistent documentation. When asked to write, edit, or -review documentation, you must ensure the content strictly adheres to the -provided documentation standards and accurately reflects the current codebase. -Adhere to the contribution process in `CONTRIBUTING.md` and the following -project standards. - -## Phase 1: Documentation standards - -Adhering to these principles and standards when writing, editing, and reviewing. - -### Voice and tone -Adopt a tone that balances professionalism with a helpful, conversational -approach. - -- **Perspective and tense:** Address the reader as "you." Use active voice and - present tense (e.g., "The API returns..."). -- **Tone:** Professional, friendly, and direct. -- **Clarity:** Use simple vocabulary. Avoid jargon, slang, and marketing hype. -- **Global Audience:** Write in standard US English. Avoid idioms and cultural - references. -- **Requirements:** Be clear about requirements ("must") vs. recommendations - ("we recommend"). Avoid "should." -- **Word Choice:** Avoid "please" and anthropomorphism (e.g., "the server - thinks"). Use contractions (don't, it's). - -### Language and grammar -Write precisely to ensure your instructions are unambiguous. - -- **Abbreviations:** Avoid Latin abbreviations; use "for example" (not "e.g.") - and "that is" (not "i.e."). -- **Punctuation:** Use the serial comma. Place periods and commas inside - quotation marks. -- **Dates:** Use unambiguous formats (e.g., "January 22, 2026"). -- **Conciseness:** Use "lets you" instead of "allows you to." Use precise, - specific verbs. -- **Examples:** Use meaningful names in examples; avoid placeholders like - "foo" or "bar." - -### Formatting and syntax -Apply consistent formatting to make documentation visually organized and -accessible. - -- **Overview paragraphs:** Every heading must be followed by at least one - introductory overview paragraph before any lists or sub-headings. -- **Text wrap:** Wrap text at 80 characters (except long links or tables). -- **Casing:** Use sentence case for headings, titles, and bolded text. -- **Naming:** Always refer to the project as `Gemini CLI` (never - `the Gemini CLI`). -- **Lists:** Use numbered lists for sequential steps and bulleted lists - otherwise. Keep list items parallel in structure. -- **UI and code:** Use **bold** for UI elements and `code font` for filenames, - snippets, commands, and API elements. Focus on the task when discussing - interaction. -- **Links:** Use descriptive anchor text; avoid "click here." Ensure the link - makes sense out of context. -- **Accessibility:** Use semantic HTML elements correctly (headings, lists, - tables). -- **Media:** Use lowercase hyphenated filenames. Provide descriptive alt text - for all images. - -### Structure -- **BLUF:** Start with an introduction explaining what to expect. -- **Experimental features:** If a feature is clearly noted as experimental, -add the following note immediately after the introductory paragraph: - `> **Note:** This is a preview feature currently under active development.` -- **Headings:** Use hierarchical headings to support the user journey. -- **Procedures:** - - Introduce lists of steps with a complete sentence. - - Start each step with an imperative verb. - - Number sequential steps; use bullets for non-sequential lists. - - Put conditions before instructions (e.g., "On the Settings page, click..."). - - Provide clear context for where the action takes place. - - Indicate optional steps clearly (e.g., "Optional: ..."). -- **Elements:** Use bullet lists, tables, notes (`> **Note:**`), and warnings - (`> **Warning:**`). -- **Avoid using a table of contents:** If a table of contents is present, remove - it. -- **Next steps:** Conclude with a "Next steps" section if applicable. - -## Phase 2: Preparation -Before modifying any documentation, thoroughly investigate the request and the -surrounding context. - -1. **Clarify:** Understand the core request. Differentiate between writing new - content and editing existing content. If the request is ambiguous (e.g., - "fix the docs"), ask for clarification. -2. **Investigate:** Examine relevant code (primarily in `packages/`) for - accuracy. -3. **Audit:** Read the latest versions of relevant files in `docs/`. -4. **Connect:** Identify all referencing pages if changing behavior. Check if - `docs/sidebar.json` needs updates. -5. **Plan:** Create a step-by-step plan before making changes. - -## Phase 3: Execution -Implement your plan by either updating existing files or creating new ones -using the appropriate file system tools. Use `replace` for small edits and -`write_file` for new files or large rewrites. - -### Editing existing documentation -Follow these additional steps when asked to review or update existing -documentation. - -- **Gaps:** Identify areas where the documentation is incomplete or no longer - reflects existing code. -- **Structure:** Apply "Structure (New Docs)" rules (BLUF, headings, etc.) when - adding new sections to existing pages. -- **Tone:** Ensure the tone is active and engaging. Use "you" and contractions. -- **Clarity:** Correct awkward wording, spelling, and grammar. Rephrase - sentences to make them easier for users to understand. -- **Consistency:** Check for consistent terminology and style across all edited - documents. - - -## Phase 4: Verification and finalization -Perform a final quality check to ensure that all changes are correctly formatted -and that all links are functional. - -1. **Accuracy:** Ensure content accurately reflects the implementation and - technical behavior. -2. **Self-review:** Re-read changes for formatting, correctness, and flow. -3. **Link check:** Verify all new and existing links leading to or from modified - pages. -4. **Format:** Once all changes are complete, ask to execute `npm run format` - to ensure consistent formatting across the project. If the user confirms, - execute the command. diff --git a/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx b/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx index 3a944abf30..992a995de1 100644 --- a/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx +++ b/src/content/docs/en/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx @@ -13,7 +13,7 @@ menu_namespace: cliMenuAlpha import Code from '~/components/Code/Code.astro' import LinkButton from 'azion-webkit/linkbutton' -**Azion CLI** is an [open source](https://github.com/aziontech/azion-cli/) command-line interface (CLI) that lets you interact with Azion Edge Platform using a terminal. With Azion CLI, you can: +**Azion CLI** is an [open source](https://github.com/aziontech/azion-cli/) command-line interface (CLI) that lets you interact with Azion Web Platform using a terminal. With Azion CLI, you can: - Initialize, build, and deploy edge applications with a single command. - Manage all Azion products and configurations as code. diff --git a/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx b/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx index f1fb11cf6d..6182ffa0aa 100644 --- a/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx +++ b/src/content/docs/pt-br/pages/devtools/cli/azion-cli/azion-overview/azion-overview.mdx @@ -16,7 +16,7 @@ menu_namespace: cliMenuAlpha import Code from '~/components/Code/Code.astro' import LinkButton from 'azion-webkit/linkbutton' -A **Azion CLI** é uma interface de linha de comando (CLI) [open source](https://github.com/aziontech/azion-cli/) que permite interagir com a Azion Edge Platform pelo terminal. Com a Azion CLI, você pode: +A **Azion CLI** é uma interface de linha de comando (CLI) [open source](https://github.com/aziontech/azion-cli/) que permite interagir com a Azion Web Platform pelo terminal. Com a Azion CLI, você pode: - Inicializar, criar e implantar edge applications com um único comando. - Gerenciar todos os produtos e configurações da Azion como código.