docopslab-dev 0.1.0 → 0.2.0

data/docs/agent/skills/asciidoc.md

@@ -16,16 +16,13 @@ Table of Contents
 - General AsciiDoc Syntax Guidelines
 - DocOps Lab Specific Syntax Guidelines
 - Inline Syntax
-- Inline Semantics
-      - Syntax Preferences
+  - Inline Semantics
+  - Syntax Preferences
 - Block Syntax
-- Block Semantics
-      - Use Delimited Blocks
-      - Tables
-      - Example Blocks
-- Special Syntax
-- Attributes
-      - Attribute Formatting
+  - Block Semantics
+  - Use Delimited Blocks
+  - Example Blocks
+  - Attribute Formatting
 - Vale Configuration and Usage
 - Consumer Mode (Other Projects)
 
@@ -97,11 +94,11 @@ DocOps Lab documentation largely follows the conventions outlined in the [Recomm
 Reinforcements and exceptions:
 
 - Use `.adoc` extensions _execpt_ for Liquid templates used to render AsciiDoc files, which use `.asciidoc`.
+
 - Use one sentence per line formatting.
 
-   - Let hard-returns signal spaces between sentences.
-   - Also do this for major colon- or semicolon-delimited sentences.
 - Use ATX-style titles and section headings.
+
 - For DRYness, use attributes for common URLs and paths (see Attribute Formatting).
 
 ## DocOps Lab Specific Syntax Guidelines
@@ -115,7 +112,9 @@ The main purpose of inline semantics is to provide a clear indication of the rol
 We can convey semantics by way of:
 
 - declaration by element, role, or class
+
 - text style based on declaration
+
 - browser effects based on declaration and additional data
 
 We use the following inline semantic coding in DocOps Lab publications.
@@ -274,13 +273,17 @@ Example single-line admonition block syntax
 NOTE: This is a single-line admonition block.
 ```
 
-**Exception to this exception** :
-   We do not recommend the same-line syntax for admonition blocks other than `NOTE` and `TIP`. For `IMPORTANT`, `CAUTION`, and `WARNING`, use at least the 2-line syntax, if not explicit delimiters.
+<dl>
+<dt class="hdlist1">Exception to this exception</dt>
+<dd>
+We do not recommend the same-line syntax for admonition blocks other than `NOTE` and `TIP`. For `IMPORTANT`, `CAUTION`, and `WARNING`, use at least the 2-line syntax, if not explicit delimiters.
 
-   ```asciidoc
-   [IMPORTANT]
-   This is a critical notice, but it's not warning you of danger.
-   ```
+```asciidoc
+[IMPORTANT]
+This is a critical notice, but it's not warning you of danger.
+```
+</dd>
+</dl>
 
 #### Exception: Single-line terminal commands
 
@@ -304,145 +307,6 @@ echo "Hello, {what}!"
 ....
 ```
 
-### Tables
-
-Tables are a special case of block content, and they have their own syntax and limited semantics in AsciiDoc.
-
-```asciidoc
-[options="header",cols=">1,^1,^1,^1,^1,^1,^1,^1"]
-|===
-| Format | Human | Cmmts | Nesting | Langs | Apps | Git | Total
-
-| YAML
-| 5
-| 5
-| 5
-| 4
-| 4
-| 5
-| 28
-
-| TOML
-| 5
-| 5
-| 5
-| 3
-| 2
-| 5
-| 26
-
-| XML
-| 2
-| 4
-| 5
-| 5
-| 2
-| 2
-| 20
-
-| JSON
-| 3
-| 1
-| 5
-| 5
-| 3
-| 3
-| 20
-
-| CSV
-| 4
-| 0
-| 0
-| 5
-| 1
-| 3
-| 13
-|===
-```
-
-At least for tables of roughly this size and complexity, the AsciiDoc table syntax is mostly legible pre-conversion.
-
-And such tables convert fairly nicely to HTML, PDF, and even ePub output formats.
-
-Example 2. Example table output
-
-<table class="tableblock frame-all grid-all stretch">
-<colgroup>
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-right valign-top">Format</th>
-<th class="tableblock halign-center valign-top">Human</th>
-<th class="tableblock halign-center valign-top">Cmmts</th>
-<th class="tableblock halign-center valign-top">Nesting</th>
-<th class="tableblock halign-center valign-top">Langs</th>
-<th class="tableblock halign-center valign-top">Apps</th>
-<th class="tableblock halign-center valign-top">Git</th>
-<th class="tableblock halign-center valign-top">Total</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-right valign-top"><p class="tableblock">YAML</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">28</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-right valign-top"><p class="tableblock">TOML</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">3</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">2</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">26</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-right valign-top"><p class="tableblock">XML</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">2</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">2</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">2</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">20</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-right valign-top"><p class="tableblock">JSON</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">3</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">3</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">3</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">20</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-right valign-top"><p class="tableblock">CSV</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">4</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">0</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">0</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">3</p></td>
-<td class="tableblock halign-center valign-top"><p class="tableblock">13</p></td>
-</tr>
-</tbody>
-</table>
-
 ### Example Blocks
 
 Use example blocks liberally. If something fits the description of being an example — especially if the words “example” or “sample” are used in the title, caption, or surrounding text referring to a given block of _anything_…​ then **wrap it in an example block**.
@@ -450,9 +314,13 @@ Use example blocks liberally. If something fits the description of being an exam
 Instances of the following block types may commonly be instances of examples, and just as commonly they may not be.
 
 - figures (diagrams, illustrations, screenshots)
+
 - tables
+
 - code listings
+
 - literal blocks (sample prompts, logs, etc)
+
 - rich-text snippets (rendered results, a user story, etc)
 
 Whenever any such instances _are examples_, prepend and append them with example blocks, and prefer to title them at the exampple-block level rather than the inner-content level.
@@ -471,61 +339,11 @@ require 'jekyll'
 ====
 ```
 
-## Special Syntax
-
-### Attributes
-
 ### Attribute Formatting
 
 AsciiDoc attributes are often used to store reusable matter. In certain contexts, attributes should follow a formatting convention that makes them easier to name and recall.
 
-#### Boolean Attributes
-
-Use toggles to set or conditionalize states such as:
-
-- intended audience type or role
-
-   - `audience-agent`
-   - `audience-beginner`
-   - ``
-- target platform or format
-
-   - `env-github`
-   - `site-gen-jekyll`
-   - `backend-pdf`
-
-These kinds of attributes are passed depending on how the AsciiDoc is converted. Platform and format indicators tend to get argued by the converter at runtime.
-
-But you can also look check for statuses that might be set in previous files depending on the use-case of the output.
-
-Testing for _existence_ of a target platform
-
-```asciidoc
-ifdef::audience-level-beginner[]
-As a beginner, you will see extra content in parts of this guide.
-
-If you are an expert, skip to the <<expert-guide>>.
-endif::[]
-```
-
-Testing for _non-existence_ of a target audience type.
-
-```asciidoc
-ifndef::audience-agent[]
-This content is _not_ to appear in docs generated for AI agents.
-endif::[]
-```
-
-It is generally advised to create two versions of any such indicator that may need to be resolve a variable placeholder later.
-
-Setting open-ended key and boolean simultaneously
-
-```asciidoc
-:audience-level: beginner
-:audience-level-beginner: true
-
-Later we can reference the {audience-level}, which might be overwritten by an attribute passed at runtime.
-```
+For a complete guidance on attribute naming and usage, see [DocOps Lab AsciiDoc Attributes Naming and Usage](/docs/asciidoc-attributes/).
 
 #### URL Attributes
 
@@ -539,20 +357,15 @@ Where:
 
 - `syntax_` is one of
 
-   - `href_` (external)
-   - `xref_` (local)
-   - none (skip it — presumed to be a straight URL)
 - `area_` is a component or category like `docs_` or `pages_`, mainly to ensure unique slugs across divisions
-- `form` is the way the resource is presented:
 
-   - `link` (includes linked text _and_ the URL)
-   - `url` (just the URL)
+- `form` is the way the resource is presented:
 
 Examples
 
 ```asciidoc
-:docopslab_hub_url: https://github.com/DocOps
-:href_docopslab_aylstack_url: {docopslab_hub_url}/aylstack/
+:docopslab_src_www_url: https://github.com/DocOps
+:href_docopslab_aylstack_url: {docopslab_src_www_url}/aylstack/
 :href_docopslab_aylstack_link: link:{href_docopslab_aylstack_url}[AYL DocStack]
 ```
 
@@ -566,44 +379,58 @@ Linting for documentation quality and consistency, both AsciiDoc markup syntax a
 
 This tool provides a custom styles package and a modified configuration system, enabling multi-file merging.
 
-**Base config** :
-   `.config/.vendor/docopslab/vale.ini` (from source)
-
-**Project config** :
-   `.config/vale.local.ini` (inherits via `BasedOnStyles`)
-
-**Ephemeral config** :
-   `.config/vale.ini` (merged from base and target)
-
-**Sync command** :
-   `bundle exec rake labdev:sync:vale`
-
-### Consumer Mode (Other Projects)
+<dl>
+<dt class="hdlist1">Base config</dt>
+<dd>
+`.config/.vendor/docopslab/vale.ini` (from source)
+</dd>
+<dt class="hdlist1">Project config</dt>
+<dd>
+`.config/vale.local.ini` (inherits via `BasedOnStyles`)
+</dd>
+<dt class="hdlist1">Ephemeral config</dt>
+<dd>
+`.config/vale.ini` (merged from base and target)
+</dd>
+<dt class="hdlist1">Sync command</dt>
+<dd>
+`bundle exec rake labdev:sync:vale`
+</dd>
+</dl>
+
+## Consumer Mode (Other Projects)
 
 For all other projects, the gem works in a standard package consumption mode:
 
 - The project’s `vale.ini` should list all desired packages, including a URL to the stable, published `DocOpsLabStyles.zip`.
+
 - The `labdev:sync:styles` task simply runs `vale sync` in the proper context, downloading all listed packages into a local `.vale/styles` directory.
 
-> **TIP:** The `labdev:sync:vale` task updates both the base config and the styles package.
+> **TIP:** The `labdev:sync:vale` task updates both the base config and the style packages.
+
+A project’s `.config/vale.local.ini` should look something like the one for this repository (DocOps/lab).
 
-The `.config/vale.ini` for consumer projects (based on the gem’s template) should look like this:
+A snippet from DocOps/lab’s `.config/vale.local.ini`
 
 ```ini
-# CONSUMER MODE CONFIG
+MinAlertLevel = warning
+StylesPath = .vendor/vale/styles
 
-StylesPath = .vale/styles
+[asciidoctor]
+missing-attribute = drop
+safe = unsafe
+experimental = YES
 
-# List all packages, including the URL to the central DocOpsLabStyles package.
-# TODO: Update with the real URL.
-Packages = RedHat, proselint, write-good, https://example.com/path/to/DocOpsLabStyles.zip
+[_blog/*.adoc]
+DocOpsLab-AsciiDoc.ExplicitSectionIDs = NO
 
-[*.adoc]
-BasedOnStyles = RedHat, DocOpsLab-Authoring, DocOpsLab-AsciiDoc
+[_docs/agent/**/*.adoc]
+DocOpsLab-AsciiDoc.ExplicitSectionIDs = NO
+DocOpsLab-AsciiDoc.ExtraLineBeforeLevel1 = NO
 ```
 
 This dual-mode system provides a robust workflow for both developing and consuming the centralized Vale styles.
 
-> **NOTE:** For full Vale configuration settings (“keys”) reference, see [the Vale documentation](https://vale.sh/docs/configuration).
+> **NOTE:** For full Vale configuration settings (“keys”) reference, see the [official Vale documentation](https://vale.sh/docs/vale-ini).
 > **NOTE:** For information on managing DocOps Lab’s Vale styles, see [the `docopslab-dev` gem README](https://github.com/DocOps/lab/blob/main/gems/docopslab-dev/README.adoc).
 

data/docs/agent/skills/bash-cli-dev.md

@@ -0,0 +1,135 @@
+# Bash CLI Development for Agents
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+> **TIP:** Use this guide in combination with the general Bash coding skill.
+
+Table of Contents
+
+- Bash CLIs
+  - Bash CLI Model
+- General CLI Principles
+  - When NOT to Use a CLI
+  - Semantic CLI Namespaces
+  - General CLI Conventions
+
+## Bash CLIs
+
+Bash scripts are often used for simple CLIs that wrap around more complex operations. Most repo-wide chores that do not require specialized Ruby-based tools like Asciidoctor or other gems are handled with Bash scripts (The significant exception to this are multi-repo libraries like the [DocOps Lab Devtool](/docs/lab-dev-setup/).)
+
+The one truly major Bash CLI we maintain is `docksh`, our Docker shell utility for launching properly configured containers for development, testing, and deployment (sourced in `box`).
+
+### Bash CLI Model
+
+Base CLIs are relatively open ended. Developers should consider how the script might change, but unless it is intended to be elaborate from the start, there is not much reason to fuss over complicated structures.
+
+> **TIP:** See [DocOps Lab Bash Coding Guide](/docs/bash-styles/) for details about implementing Bash CLIs.
+
+Let’s examine our typical Bash script CLI structure:
+
+```
+./bashscript.sh [arguments] [options]
+```
+
+If a Bash script is likely to eventually need to encompass multiple arguments or options, consider making it a Rake task and invoking Ruby scripts, instead.
+
+## General CLI Principles
+
+Most of our user-facing applications are Ruby gems, and most of those are intended to be used via three primary interfaces:
+
+1. An application specific, openly designed CLI utility.
+
+2. An application configuration file.
+
+3. Subject-matter content or domain-specific data of some kind.
+
+By way of these three interfaces, users can operate the application in a way that is optimized for their particular use case.
+
+CLIs should allow for runtime configuration overrides and even runtime content/data overrides. But most of all they should focus on conveniently putting power in users' hands.
+
+This means leaving the CLI model open to the task at hand, but it also means adhering to some conventions that apply generally to both Ruby and Bash CLIs.
+
+### When NOT to Use a CLI
+
+Even when an application offers a mature, well-designed CLI, there are times when either an application programming interface (API) or a domain-specific language (DSL) is preferable. Typically we want to keep complicated shell commands out of core products and CI/CD pipelines, in favor of native or RESTful APIs or else config-driven or DSL-driven utilities.
+
+### Semantic CLI Namespaces
+
+When designing CLIs, consider the namespaces of the elements we use: subcommands, arguments, and options/flags.
+
+Subcommands should be verbs or nouns that declare operations or contexts. At each position, these elements should be organizable into meaningful categories.
+
+Arguments should be meaningful nouns that represent the primary _subject or subjects_ of the command.
+
+### General CLI Conventions
+
+The definitive reference on CLI design is the [CLI Guidelines](https://clig.dev/) project.
+
+#### Option format
+
+<dl>
+<dt class="hdlist1">Use spaces rather than `=` to assign values to options.</dt>
+<dd>
+Flag forms such as `--option-name value` are preferred over `--option-name=value`.
+</dd>
+<dt class="hdlist1">Provide long- and short- form flag aliases for common options.</dt>
+<dd>
+For ex: `-h` and `--help`, `-c` and `--config`.
+</dd>
+<dt class="hdlist1">Use `--no-` prefix for negated boolean flags when applicable.</dt>
+<dd>
+For ex: `--no-cache` to disable caching.
+</dd>
+</dl>
+
+#### Command structure
+
+<dl>
+<dt class="hdlist1">Use subcommand only with apps that perform categorically diverse operations,</dt>
+<dd>
+Prefer flag combinations when possible. Subcommands signal a shift in execution context, and thus they can be greatly helpful when needed. Otherwise, reserve the first argument slot for something a meaningful arbitrary argument.
+
+A CLI with very handy subcommands
+
+```
+git fetch
+git commmit
+git merge
+```
+
+No subcommand needed
+
+```
+rhx 1.2.1 --config test-config.yml --mapping apis/jira.yml --verbose --fetch --yaml
+rhx 1.2.1 --config test-config.yml --html
+```
+
+And yes, of course you can combine fixed subcommands with arbitrary arguments.
+
+```
+git diff README.adoc
+```
+</dd>
+<dt class="hdlist1">Avoid using Unix-style argument structures.</dt>
+<dd>
+Arbitrary arguments should come _before_ options, even if that is counter-intuitive. Typically in our apps, users are modifying commands that get executed on the same target, so if the target is an arbitrary file path or version number, it should closely follow the command as an early argument.
+
+Preferred argument order
+
+```
+cliname targetfile --option1 value1 --option2 value2 --verbose --force
+```
+
+This structure lets users more conveniently change the parts of the command-line that will need more frequent changing.
+</dd>
+<dt class="hdlist1">Accommodate Unix-style CLIs by adding named options for every arbitrary argument supported.</dt>
+<dd>
+The trick is to enable those cases where the subject path or code _is_ what gets changed most often.
+
+```
+rhx --yaml --version 1.2.6
+rhx --yaml --version 1.3.1
+```
+</dd>
+</dl>
+