doc(doc-site): document the CLI tools codescan ships

docs/doc-site/_index.md

@@ -5,6 +5,8 @@ description: Generate Swagger 2.0 specifications from annotated Go source code.
 weight: 1
 ---
 
+{{< version >}}
+
 `github.com/go-openapi/codescan` is a Go source code scanner that produces
 [Swagger 2.0][swagger2] (OpenAPI 2.0) specifications.
 
@@ -26,6 +28,8 @@ The only exposed API is `Run()` and `Options`.
 
 ### Getting started
 
+To use codescan in your go program:
+
 ```cmd
 go get github.com/go-openapi/codescan
 ```
@@ -40,73 +44,36 @@ swaggerSpec, err := codescan.Run(&codescan.Options{
 })
 ```
 
-### Where to go next
-
-{{< cards >}}
-{{% card title="About" %}}
-What codescan is, why scan source to a spec, and how it relates to go-swagger.
-
-→ [about]({{% relref "/about" %}})
-{{% /card %}}
-
-{{% card title="Getting started" %}}
-Install the scanner, annotate a package, and produce your first spec.
-
-→ [getting-started]({{% relref "/getting-started" %}})
-{{% /card %}}
-
-{{% card title="Tutorials" %}}
-Learn by spec concept — model definitions, routes, validations — annotated Go
-next to the spec it produces.
-
-→ [tutorials]({{% relref "/tutorials" %}})
-{{% /card %}}
-
-{{% card title="Shaping the output" %}}
-How-to guides for the rendering knobs: $ref vs inline, aliases, nullable
-pointers, extensions.
+Or as a command, to run in a build or a pipeline:
 
-→ [shaping-the-output]({{% relref "/shaping-the-output" %}})
-{{% /card %}}
-
-{{% card title="Annotation index" %}}
-Every annotation at a glance, linked to its worked example and its full
-reference.
-
-→ [annotation-index]({{% relref "/annotation-index" %}})
-{{% /card %}}
-
-{{% card title="Reference (maintainers)" %}}
-The complete compendium — annotations, keywords, sub-languages and the formal
-grammar.
-
-→ [maintainers]({{% relref "/maintainers" %}})
-{{% /card %}}
+```cmd
+go install github.com/go-openapi/codescan/cmd/genspec@latest
+```
 
-{{% card title="Project" %}}
-Repo overview, license and links to the shared go-openapi guides.
+Or as a terminal front-end, to watch a spec take shape as you annotate:
 
-→ [project]({{% relref "/project" %}})
-{{% /card %}}
-{{< /cards >}}
+```cmd
+go install github.com/go-openapi/codescan/cmd/genspec-tui@latest
+```
 
-## Licensing
+Try it out now from your browser in our [Playground]({{% relref "/playground" %}}).
 
-`SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers`
+### Relationship to go-swagger
 
-This library ships under the [Apache-2.0 license](./project/license/).
+`go-swagger` is a CLI tool that consumes the codescan library.
+It works exactly on the same set of annotations.
 
-## Contributing
+The main differences with the newer `genspec` CLI shipped by this project are:
 
-Issues and pull requests welcome.
+* release cadence (expect slightly less frequent updates on go-swagger, which has more dependencies and constraints)
+* package distribution: at this moment, the codescan CLI tools do not ship as distro packages or docker images
+* exposed CLI knobs and default settings (defaults need to be backward-compatible for go-swagger users)
 
-See the shared [go-openapi contributing guidelines][contributing-doc-site] and
-the per-repo notes in [project/](./project/).
+`genspec` and `genspec-tui` are intended for users who want tools leaner than go-swagger, or who want to
+experiment with the latest features.
 
----
+### Where to go next
 
 {{< children type="card" description="true" >}}
 
 [swagger2]: https://swagger.io/specification/v2/
-[contributing-doc-site]: https://go-openapi.github.io/doc-site/contributing/contributing/index.html
-[maintainers-doc-site]: https://go-openapi.github.io/doc-site/maintainers/index.html

docs/doc-site/about.md

@@ -2,8 +2,9 @@
 title: About
 weight: 5
 description: |
-  What codescan is, why you would scan source to produce a spec, and how it
-  relates to the go-swagger toolkit.
+  What codescan is, why you would scan source to produce a spec.
+
+  How does it relate to the go-openapi & go-swagger toolkits.
 ---
 
 `codescan` is a **code-first** OpenAPI engine: it reads specially formatted
@@ -13,35 +14,43 @@ comments (annotations) in your Go source and produces a
 
 ## Two ways to build an API
 
-APIs and their documentation tend to evolve along one of two paths. The
-go-openapi / go-swagger toolkit supports both.
+APIs and their documentation tend to evolve along one of two paths. The go-openapi / go-swagger toolkit supports both.
+
+- **Design-first** (contract-first) — you write the OpenAPI document first and treat it as the contract,
+  then generate servers and clients from it.
+
+> If this is your workflow, you should reach for [go-swagger][go-swagger] (`swagger generate server` / `swagger generate client`).
 
-- **Design-first** (contract-first) — you write the OpenAPI document first and
-  treat it as the contract, then generate servers and clients from it. If this
-  is your workflow, reach for [go-swagger][go-swagger] (`swagger generate
-  server` / `swagger generate client`).
-- **Code-first** — you write annotated Go and scan it to produce the spec. This
-  keeps the document in sync with the code as it changes, and lets you produce a
-  valid specification for a service that already exists.
+- **Code-first** — you write annotated Go and scan it to produce the spec.
+
+> This keeps the document in sync with the code as it changes, and lets you produce a valid specification for a service that already exists.
 
 **codescan is the engine for the code-first path.**
 
 ## Relationship to go-swagger
 
 codescan began life as a single package inside [go-swagger][go-swagger] and was
-spun out into its own [go-openapi][go-openapi] repository. It is the scanner
-**behind** the go-swagger command:
+spun out into its own [go-openapi][go-openapi] repository. It is the scanner **behind** the go-swagger command:
 
 ```sh
 swagger generate spec ./...
 ```
 
-go-swagger remains the main command-line consumer of this library. This site
-documents the **scanner library itself** — the layer beneath `swagger generate
-spec` — so it sits upstream of go-swagger's "generate spec" documentation. If
-you arrived here from go-swagger: the annotations are exactly the same, and you
-can either keep using the `swagger` CLI or call `codescan.Run` directly from
-your own program (see [Getting started]({{% relref "/getting-started" %}})).
+For now, go-swagger remains the main command-line consumer of this library.
+
+This site documents the **scanner library itself** — the layer beneath `swagger generate spec` —
+so it sits upstream of go-swagger's "generate spec" documentation.
+
+If you arrived here from go-swagger: the annotations are exactly the same, and you can either keep using the
+`swagger` CLI or call `codescan.Run` directly from your own program
+(see [Getting started]({{% relref "/getting-started" %}})).
+
+{{% notice info %}}
+codescan now releases standalone CLI tools that ship independently from go-swagger:
+`genspec`, `genspec-wasi` and `genspec-tui`.
+
+These are supplementary tools, not a replacement, and go-swagger will continue shipping updates from this library.
+{{% /notice %}}
 
 ## Why scan from source
 
@@ -53,18 +62,18 @@ your own program (see [Getting started]({{% relref "/getting-started" %}})).
   that is already deployed, so it becomes interoperable with new clients and
   tooling.
 
-When document-level metadata (info, security, servers) is more naturally
-hand-authored, you do not have to push it into the code: scan the code for the
-operations and models, and **overlay** the result onto a hand-written base
-document (see [Shaping the output → Overlaying a spec]({{% relref "overlaying-a-spec" %}})).
+When document-level metadata (info, security, servers) is more naturally hand-authored,
+you do not have to push it into the code: scan the code for the operations and models,
+and **overlay** the result onto a hand-written base document
+(see [Shaping the output → Overlaying a spec]({{% relref "overlaying-a-spec" %}})).
+
+## The go-openapi toolkit
 
-## A community toolkit
+go-openapi and go-swagger are community-driven, open-source **building blocks** meant to be assembled and customized
+— there are too many ways to approach APIs to cover them all.
 
-go-openapi and go-swagger are community-driven, open-source **building blocks**
-meant to be assembled and customized — there are too many ways to approach APIs
-to cover them all. Fork, reuse, and adapt what you find useful. See the
-[go-swagger project's "About" page][go-swagger-about] for the wider toolkit
-story.
+Fork, reuse, and adapt what you find useful. See the [go-swagger project's "About" page][go-swagger-about]
+for the wider toolkit story.
 
 ## Where to go next
 

docs/doc-site/annotation-index/_index.md

@@ -1,13 +1,15 @@
 ---
 title: Annotation index
-weight: 40
+weight: 60
 description: |
-  Every swagger:* annotation at a glance — what it produces and where it
-  attaches — linked to both its worked example and its full reference.
+  Every swagger:* annotation at a glance.
+
+  What it produces and where it attaches — linked to both its worked example and its full reference.
 ---
 
-The complete `swagger:*` vocabulary, one row each. **By example** jumps to the
-tutorial that shows the annotation as runnable Go next to the spec it produces;
+The complete `swagger:*` vocabulary, one row each.
+
+**By example** jumps to the tutorial that shows the annotation as runnable Go next to the spec it produces;
 **Reference** jumps to the exhaustive rule in the Maintainers compendium.
 
 | Annotation | Attaches to | Produces | By example | Reference |

docs/doc-site/getting-started/_index.md

@@ -2,8 +2,9 @@
 title: Getting started
 weight: 10
 description: |
-  Install codescan and choose how to drive it — as a Go library from your own
-  program, or interactively from the terminal UI.
+  Install codescan and choose how to drive it.
+
+  As a Go library from your own program, as a command in a build, or interactively from the terminal UI.
 ---
 
 ## Install
@@ -21,15 +22,33 @@ codescan exposes a deliberately small surface: a single `Run` function and an
 func Run(opts *Options) (*spec.Swagger, error)
 ```
 
+---
+
+Or as a command, to run in a build or a pipeline:
+
+```cmd
+go install github.com/go-openapi/codescan/cmd/genspec@latest
+```
+
+---
+
 Or as a terminal front-end, to watch a spec take shape as you annotate:
 
 ```cmd
 go install github.com/go-openapi/codescan/cmd/genspec-tui@latest
 ```
 
+---
+
+If you just want to experiment, learn or reproduce an issue you're currently having,
+the easiest way is to try our [Playground]({{% relref "/playground" %}}) in your browser.
+
 ## Ways to use codescan
 
 {{< children type="card" description="true" >}}
 
-> Both drive the same scanner over the same annotations, so what you see in the
-> terminal UI is what your generator will produce.
+> All three drive the same scanner over the same annotations, and every knob is
+> spelled the same way in each — so what you see in the terminal UI is what your
+> build will produce.
+>
+> See [Setting an option]({{% relref "setting-options" %}}).