docopslab-dev 0.1.0 → 0.2.0

data/docs/agent/skills/write-the-docs.md

@@ -13,20 +13,28 @@ Table of Contents
 
 - GitHub Issues Labels
 - Change Documentation
+  - User-Facing Documentation
+  - Internal Documentation
 - Release Note Entry
 
 ## GitHub Issues Labels
 
 GitHub Issues are use specific labels to indicate documentation expectations.
 
-**`needs:docs`** :
-   The issue requires documentation updates as part of its resolution. Documentation updates will likely be in a sub-issue with a `documentation` label.
-
-**`needs:note`** :
-   The issue requires a note in the release history when resolved. Release notes are appended to the description body under `## Release Note`.
-
-**`changelog`** :
-   The issue summary should be included in the changelog for the next release, even if no release note is included.
+<dl>
+<dt class="hdlist1">`needs:docs`</dt>
+<dd>
+The issue requires documentation updates as part of its resolution. Documentation updates will likely be in a sub-issue with a `documentation` label.
+</dd>
+<dt class="hdlist1">`needs:note`</dt>
+<dd>
+The issue requires a note in the release history when resolved. Release notes are appended to the description body under `## Release Note`.
+</dd>
+<dt class="hdlist1">`changelog`</dt>
+<dd>
+The issue summary should be included in the changelog for the next release, even if no release note is included.
+</dd>
+</dl>
 
 Issues labeled `changelog` will automatically appear in the Changelog section of the Release History document. Release notes must be manually entered.
 
@@ -38,6 +46,59 @@ For early product versions, most documentation appears in the root `README.adoc`
 
 Reference matter should be documented where it is defined, such as in `specs/data/*.yml` files.
 
+When a product matures (prior to 1.0), the documentation should move into new paths, separated depending on whether it is user-facing or internal.
+
+In either case, the way to discover where to put documentation changes is to use a `docopslab-dev` _skim_ task on the existing docs source. These skims are semantic outlines of the source files in their converted state. They can be used for navigation, content discovery, and change impact analysis.
+
+### User-Facing Documentation
+
+End-user docs, including API documentation, is usually sourced in `docs/content/`, alongside asset files for the documentation site (images, CSS, etc.).
+
+The `docs/` path is typically a Jekyll site’s source path, but in most cases a pre-build operation will generate supplemental files in `docs/built/` or the like.
+
+If the changes you are documenting are user-facing, use the tasks below to determine where the relevant documentation lives.
+
+<dl>
+<dt class="hdlist1">Skim the docs</dt>
+</dl>
+
+```
+bundle exec rake labdev:skim:adoc[README.adoc,tree,json] > .agent/docs/readme.json
+bundle exec rake labdev:skim:adoc[docs/,tree,json] > .agent/docs/skim-docs.json
+```
+
+### Internal Documentation
+
+Generally speaking, internal documentation (for developers, maintainers, and their AI agents), belongs in `_docs/` and `.agent/docs/` paths.
+
+The `_docs/agent/` path is for overlays that take priority over parallel docs in `.agent/docs/` (maintained by docopslab-dev library syncing).
+
+<dl>
+<dt class="hdlist1">Skim the README</dt>
+</dl>
+
+```
+bundle exec rake labdev:skim:adoc[README.adoc,tree,json] > .agent/docs/readme.json
+```
+
+<dl>
+<dt class="hdlist1">Skim the internal docs</dt>
+</dl>
+
+```
+bundle exec rake labdev:skim:adoc[_docs/,tree,json] > .agent/docs/skim-internal.json
+```
+
+<dl>
+<dt class="hdlist1">Skim the agent docs to see if any overlay is needed</dt>
+</dl>
+
+```
+bundle exec rake labdev:skim:md[.agent/docs/:_docs/agent/,tree,json] > .agent/docs/skim-agent.json
+```
+
+If a local instruction contradicts or differs arbitrarily from the main DocOps Lab developer/contributor docs, create an overlay file in `_docs/agent/*` with the same sub-path and filename.
+
 ## Release Note Entry
 
 User-facing product changes that deserve explanation (not just notice) require a release note.
@@ -49,6 +110,7 @@ Example
 ```markdown
 ## Release Note
 
-The content of the release note goes here, in Markdown format. Try to keep it to one paragraph with minimal formatting.
+The content of the release note goes here, in Markdown format.
+Try to keep it to one paragraph with minimal formatting.
 ```
 

data/docs/agent/topics/common-project-paths.md

@@ -22,96 +22,148 @@ Table of Contents
 
 Only two files are required in _every_ DocOps Lab project, though most projects should contain most of these files, depending on the nature of the codebase. A `docs/` or `_docs/` directory is close to the third universal requirement, necessary by the time a project reaches version 1.0.0.
 
-**`README.adoc`** :
-   Project documentation in AsciiDoc format, providing an overview and instructions. DocOps Lab READMEs typically include single-sourcing data for the product as AsciiDoc attributes. See the Sourcerer project.
-
-**`LICENSE`** :
-   The project’s license file, specifying the terms under which the code can be used and distributed. Almost always **MIT License**.
-
-**`docs/` / `_docs/`** :
-   Directory for additional documentation, guides, and related materials. Typically `docs/` for product _user_ documentation, whereas `_docs/` is for (a) repos that are mainly for websites or (b) _internal engineering_ documentation files (more often found at `docs/_docs/`). Both might be present in the case of a website that hosts docs and _has its own_ docs.
-
-   A `docs/` directory will typically have its own `Gemfile`, configs, and assets for Jekyll, Yard, and other generators. A `_docs/` directory is usually a content-only subordinate to the main project and its content, and may not have separate configs or assets.
+<dl>
+<dt class="hdlist1">`README.adoc`</dt>
+<dd>
+Project documentation in AsciiDoc format, providing an overview and instructions. DocOps Lab READMEs typically include single-sourcing data for the product as AsciiDoc attributes. See the [AsciiSourcerer project](https://github.com/DocOps/asciisourcerer).
+</dd>
+<dt class="hdlist1">`LICENSE`</dt>
+<dd>
+The project’s license file, specifying the terms under which the code can be used and distributed. Almost always **MIT License**.
+</dd>
+<dt class="hdlist1">`docs/` / `_docs/`</dt>
+<dd>
+Directory for additional documentation, guides, and related materials. Typically `docs/` for product _user_ documentation, whereas `_docs/` is for (a) repos that are mainly for websites or (b) _internal engineering_ documentation files (more often found at `docs/_docs/`). Both might be present in the case of a website that hosts docs and _has its own_ docs.
+
+A `docs/` directory will typically have its own `Gemfile`, configs, and assets for Jekyll, Yard, and other generators. A `_docs/` directory is usually a content-only subordinate to the main project and its content, and may not have separate configs or assets.
+</dd>
+</dl>
 
 ## Configuration
 
-**`.config/`** :
-   Configuration files for tooling used in development, building, or QA/testing. Not always used.
-
-   **`.config/releasehx.yml`** :
-      Configuration file for ReleaseHx, a tool for generating release notes and changelogs.
-
-   **`.config/jekyll.yml`** :
-      Configuration file for Jekyll docs publication. For Jekyll extensions (themes and plugins), this file is typically `./_config.yml` to conform to Jekyll defaults.
-
-   **`.config/vale.ini`** :
-      Configuration file for Vale, a linter for prose, defining linting rules and styles.
-
-**`.config/.vendor/`** :
-   Directory for upstream configuration files, mostly or entirely managed by `docopsab-dev` gem. These files are not tracked in Git but are synced with upstream sources and maintained by DocOps Lab.
+<dl>
+<dt class="hdlist1">`.config/`</dt>
+<dd>
+Configuration files for tooling used in development, building, or QA/testing. Not always used.
+
+<dl>
+<dt class="hdlist1">`.config/releasehx.yml`</dt>
+<dd>
+Configuration file for ReleaseHx, a tool for generating release notes and changelogs.
+</dd>
+<dt class="hdlist1">`.config/jekyll.yml`</dt>
+<dd>
+Configuration file for Jekyll docs publication. For Jekyll extensions (themes and plugins), this file is typically `./_config.yml` to conform to Jekyll defaults.
+</dd>
+<dt class="hdlist1">`.config/vale.ini`</dt>
+<dd>
+Configuration file for Vale, a linter for prose, defining linting rules and styles.
+</dd>
+</dl>
+</dd>
+<dt class="hdlist1">`.config/.vendor/`</dt>
+<dd>
+Directory for upstream configuration files, mostly or entirely managed by `docopsab-dev` gem. These files are not tracked in Git but are synced with upstream sources and maintained by DocOps Lab.
+</dd>
+</dl>
 
 ## Containerization
 
-**`Dockerfile`** :
-   Dockerfile for building the project’s Docker image, defining the environment and dependencies.
-
-**`.dockerignore`** :
-   Specifies files and directories to ignore when building the Docker image.
-
-**`docker-compose.yml`** :
-   Defines and runs multi-container Docker applications, _if applicable_.
+<dl>
+<dt class="hdlist1">`Dockerfile`</dt>
+<dd>
+Dockerfile for building the project’s Docker image, defining the environment and dependencies.
+</dd>
+<dt class="hdlist1">`.dockerignore`</dt>
+<dd>
+Specifies files and directories to ignore when building the Docker image.
+</dd>
+<dt class="hdlist1">`docker-compose.yml`</dt>
+<dd>
+Defines and runs multi-container Docker applications, _if applicable_.
+</dd>
+</dl>
 
 ## Ruby Files
 
 These files are common to Ruby-based DocOps Lab projects. The `Gemfile` and `Gemfile.lock` may be present in non-Ruby codebases that use Ruby development dependencies, such as ReleaseHx.
 
-**`Gemfile`** :
-   Ruby Bundler file, specifying gem dependencies for the project.
-
-**`Gemfile.lock`** :
-   Generated by Bundler, this file locks the gem versions used in the project.
-
-**`.ruby-version`** :
-   Specifies the Ruby version used in the project.
-
-**`<gemname>.gemspec`** :
-   Ruby gem specification file, defining the gem’s metadata and dependencies.
+<dl>
+<dt class="hdlist1">`Gemfile`</dt>
+<dd>
+Ruby Bundler file, specifying gem dependencies for the project.
+</dd>
+<dt class="hdlist1">`Gemfile.lock`</dt>
+<dd>
+Generated by Bundler, this file locks the gem versions used in the project.
+</dd>
+<dt class="hdlist1">`.ruby-version`</dt>
+<dd>
+Specifies the Ruby version used in the project.
+</dd>
+<dt class="hdlist1">`<gemname>.gemspec`</dt>
+<dd>
+Ruby gem specification file, defining the gem’s metadata and dependencies.
+</dd>
+</dl>
 
 ## Automation Paths
 
-**`Rakefile`** :
-   Ruby Rakefile for defining tasks and automation scripts.
-
-**`scripts/`** :
-   Custom scripts for automating tasks related to development, testing, and deployment. See [scripts] below.
-
-**`.github/workflows/`** :
-   GitHub Actions workflows for CI/CD, defining automated build, test, and deployment processes.
+<dl>
+<dt class="hdlist1">`Rakefile`</dt>
+<dd>
+Ruby Rakefile for defining tasks and automation scripts.
+</dd>
+<dt class="hdlist1">`scripts/`</dt>
+<dd>
+Custom scripts for automating tasks related to development, testing, and deployment.
+</dd>
+<dt class="hdlist1">`.github/workflows/`</dt>
+<dd>
+GitHub Actions workflows for CI/CD, defining automated build, test, and deployment processes.
+</dd>
+</dl>
 
 ## Quality Assurance Paths
 
 Any files containing _requirements_, _specifications_, _definitions_, _schemas_, or _tests_ should be stored in the `specs/` directory, as detailed in [DocOps Lab Testing & Specifications](/docs/testing/).
 
-**`specs/`** :
-   General directory for content that specifies, defines, or tests elements of the product. See [DocOps Lab Testing & Specifications](/docs/testing/).
-
-   **`specs/data/`** :
-      Definition and schema files.
-
-   **`specs/tests/rspec/`** :
-      RSpec tests for Ruby codebases.
-
-   **`../<product-slug>-demo/`** :
-      Major products typically have a sibling repo that serves as a proving grounds and/or for demonstrative purposes.
+<dl>
+<dt class="hdlist1">`specs/`</dt>
+<dd>
+General directory for content that specifies, defines, or tests elements of the product. See [DocOps Lab Testing & Specifications](/docs/testing/).
+
+<dl>
+<dt class="hdlist1">`specs/data/`</dt>
+<dd>
+Definition and schema files.
+</dd>
+<dt class="hdlist1">`specs/tests/rspec/`</dt>
+<dd>
+RSpec tests for Ruby codebases.
+</dd>
+<dt class="hdlist1">`../<product-slug>-demo/`</dt>
+<dd>
+Major products typically have a sibling repo that serves as a proving grounds and/or for demonstrative purposes.
+</dd>
+</dl>
+</dd>
+</dl>
 
 ## Generative AI Paths
 
-**`.github/copilot-instructions.md`** :
-   Instructions for GitHub Copilot, providing guidance on how any cloud-based GH Copilot assistance should be oriented toward a given codebase.
-
-**`AGENTS.md`** :
-   General for _local_ coding agents. May duplicate `.github/copilot-instructions.md` or provide additional context.
-
-**`.agent/`** :
-   A directory for temporary/scratch files used by local coding agents.
+<dl>
+<dt class="hdlist1">`.github/copilot-instructions.md`</dt>
+<dd>
+Instructions for GitHub Copilot, providing guidance on how any cloud-based GH Copilot assistance should be oriented toward a given codebase.
+</dd>
+<dt class="hdlist1">`AGENTS.md`</dt>
+<dd>
+General for _local_ coding agents. May duplicate `.github/copilot-instructions.md` or provide additional context.
+</dd>
+<dt class="hdlist1">`.agent/`</dt>
+<dd>
+A directory for temporary/scratch files used by local coding agents.
+</dd>
+</dl>
 

data/docs/agent/topics/dev-tooling-usage.md

@@ -2,24 +2,32 @@
 
 This document is intended for AI agents operating within a DocOps Lab environment.
 
-This guide pertains to the `docopslab-dev` environment. For complete documentation, see the [project’s README](https://github.com/DocOps/lab/blob/main/gems/docopslab-dev/README.adoc).
+This guide pertains to the `docopslab-dev` environment. For complete documentation, see the [project’s README](/projects/docops-box/).
 
-> **IMPORTANT:** The environment described and provided here is _not_ optimized for DocOps Lab _applications_ used in third-party projects. For your own applications of DocOps Labs products like ReleaseHx and Issuer, see [DocOps Box](https://github.com/DocOps/box) for a full-featured docs-focused workspace, runtime, and production environment.
+> **IMPORTANT:** The environment described and provided here is _not_ optimized for DocOps Lab _applications_ used in third-party projects. For your own applications of DocOps Labs products like ReleaseHx and Issuer, see [DocOps Box](/projects/docops-box) for a full-featured docs-focused workspace, runtime, and production environment.
 
-This gem mainly supplies rake tasks for performing common development operations across unified configurations and sub-libraries.
+This gem mainly supplies rake tasks for performing common development operations across and between projects.
 
 Table of Contents
 
 - Standard Usage
 - Override Commands
-- More Example Commands
-- Tasks and Workflow
-- Typical Workflow
+- Task Reference
+  - Typical Workflow
+  - Override Commands
 - Customization
-- Local Overrides
+  - Local Overrides
 
 ## Standard Usage
 
+With a proper native Ruby environment, use the `bundle exec` prefix to ensure consistent dependency versioning.
+
+Sync all configs and assets
+
+```
+bundle exec rake labdev:sync:all
+```
+
 Run all linters
 
 ```
@@ -29,65 +37,39 @@ bundle exec rake labdev:lint:all
 Auto-fix safe issues
 
 ```
-bundle exec rake labdev:heal
+bundle exec rake labdev:heal:all
 ```
 
 ## Override Commands
 
 Most executions of the packaged tools are handled through Rake tasks, but you can always run them directly, especially to pass arguments not built into the tasks.
 
-**RuboCop** :
-   ```
-   bundle exec rubocop --config .config/rubocop.yml [options]
-   bundle exec rubocop --config .config/rubocop.yml --auto-correct-all
-   bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
-   ```
-
-**Vale** :
-   ```
-   vale --config=.config/vale.ini [options] [files]
-   vale --config=.config/vale.ini README.adoc
-   vale --config=.config/vale.ini --minAlertLevel=error .
-   ```
-
-**HTMLProofer** :
-   ```
-   bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site
-   ```
-
-## More Example Commands
-
-Lint specific Ruby file with specific rule
-
-```
-bundle exec rake 'labdev:lint:ruby[lib/myfile.rb,Style/StringLiterals]'
-```
-
-Lint all AsciiDoc files for a specific Vale rule
-
+<dl>
+<dt class="hdlist1">RuboCop</dt>
+<dd>
 ```
-bundle exec rake 'labdev:lint:adoc[,DocOpsLab-Authoring.ExNotEg]'
+bundle exec rubocop --config .config/rubocop.yml [options]
+bundle exec rubocop --config .config/rubocop.yml --auto-correct-all
+bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
 ```
-
-Lint specific shell script
-
+</dd>
+<dt class="hdlist1">Vale</dt>
+<dd>
 ```
-bundle exec rake 'labdev:lint:bash[scripts/docksh]'
+vale --config=.config/vale.ini [options] [files]
+vale --config=.config/vale.ini README.adoc
+vale --config=.config/vale.ini --minAlertLevel=error .
 ```
-
-Lint specific file with Vale (text mode)
-
+</dd>
+<dt class="hdlist1">HTMLProofer</dt>
+<dd>
 ```
-bundle exec rake 'labdev:lint:text[_docs/myfile.adoc]'
+bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site
 ```
+</dd>
+</dl>
 
-Show a specific lint rule profile
-
-```
-bundle exec rake 'labdev:show:rule[vale,RedHat]'
-```
-
-## Tasks and Workflow
+## Task Reference
 
 ```
 bundle exec rake --tasks | grep labdev:
@@ -118,39 +100,16 @@ git commit -m "Add new feature"
 
 1. Auto-fix what you can.
 
-```
-bundle exec rake labdev:heal
-```
 2. Review the changes.
 
-```
-git diff
-```
 3. Commit the fixes.
 
-```
-git add -A
-git commit -m "Auto-fix linting issues"
-```
 4. Handle any remaining manual fixes.
 
-```
-bundle exec rake labdev:lint:all
-```
 5. Fix remaining issues manually.
 
-```
-git add -A
-git commit -m "Fix remaining linting issues"
-```
 6. Try pushing.
 
-```
-git push
-```
-
-If all blocking issues are cleared, the push should succeed. Otherwise, more cleanup is needed.
-
 > **TIP:** Bypass the pre-push gates (usually to test or demo the failure at origin):
 >
 >
@@ -161,15 +120,49 @@ If all blocking issues are cleared, the push should succeed. Otherwise, more cle
 > git push --no-verify
 > ```
 
+### Override Commands
+
+Most executions of the packaged tools are handled through Rake tasks, but you can always run them directly, especially to pass arguments not built into the tasks.
+
+<dl>
+<dt class="hdlist1">RuboCop</dt>
+<dd>
+```
+bundle exec rubocop --config .config/rubocop.yml [options]
+bundle exec rubocop --config .config/rubocop.yml --auto-correct-all
+bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
+```
+</dd>
+<dt class="hdlist1">Vale</dt>
+<dd>
+```
+vale --config=.config/vale.ini [options] [files]
+vale --config=.config/vale.ini README.adoc
+vale --config=.config/vale.ini --minAlertLevel=error .
+```
+</dd>
+<dt class="hdlist1">HTMLProofer</dt>
+<dd>
+```
+bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site
+```
+</dd>
+</dl>
+
 ## Customization
 
 Override settings by editing the project configs:
 
 - `.config/docopslab-dev.yml`
+
 - `.config/rubocop.yml`
+
 - `.config/vale.ini`
+
 - `.config/htmlproofer.yml`
+
 - `.config/actionlint.yml`
+
 - `.config/shellcheckrc`
 
 Your configurations will inherit from the base configurations and source libraries as sourced in the Git-ignored `.config/.vendor/docopslab/` path.
@@ -179,7 +172,7 @@ Your configurations will inherit from the base configurations and source librari
 Projects using `docopslab-dev` will have a configuration structure like the following:
 
 ```tree
-config/
+.config/
 ├── docopslab-dev.yml # Project manifest (tracked)
 ├── actionlint.yml # Project config (tracked; inherits from base)
 ├── htmlproofer.local.yml # Project config (tracked; inherits from base)

data/docs/agent/topics/devops-ci-cd.md

@@ -14,7 +14,7 @@ Table of Contents
 
 - Common Automation Scripts
 - Docker Usage
-- Application Dockerfiles and Images
+  - Application Dockerfiles and Images
 - See Also
 
 ## Common Automation Scripts
@@ -24,6 +24,7 @@ Some DocOps Lab projects include highly customized automation scripts, but most
 These procedures can always be invoked by way of local scripts located in `scripts/`. These include:
 
 - `build.sh`
+
 - `publish.sh`
 
 Common scripts are managed through the lnk:/docs/lab-dev-setup/[`docopslab-dev` gem].
@@ -51,5 +52,6 @@ This Dockerfile defines the image that will be built and pushed to Docker Hub fo
 ## See Also
 
 - `./dev-tooling-usage.md`
+
 - `../skills/git.md`
 

data/docs/agent/topics/product-docs-deployment.md

@@ -8,18 +8,24 @@ For less-formalized projects, documentation is restricted to `README.adoc` and o
 
 The URL structure is as follows:
 
-**Project landing page** :
-   `https://<project>.docopslab.org/`
-
-   At a minimum, this should be a subset of the `README.adoc` file.
-
-**Product user docs** :
-   `https://<project>.docopslab.org/docs/`
-
-**Product developer docs** :
-   `https://<project>.docopslab.org/docs/api/(<apiname>/)`
-
-   The final `<apiname>` directory is only applicable when the product contains multiple distinct APIs.
+<dl>
+<dt class="hdlist1">Project landing page</dt>
+<dd>
+`https://<project>.docopslab.org/`
+
+At a minimum, this should be a subset of the `README.adoc` file.
+</dd>
+<dt class="hdlist1">Product user docs</dt>
+<dd>
+`https://<project>.docopslab.org/docs/`
+</dd>
+<dt class="hdlist1">Product developer docs</dt>
+<dd>
+`https://<project>.docopslab.org/docs/api/(<apiname>/)`
+
+The final `<apiname>` directory is only applicable when the product contains multiple distinct APIs.
+</dd>
+</dl>
 
 GH Pages configuration for these sites enables deployment by way of a clean `gh-pages` branch containing only generated documentation artifacts and the `CNAME` file.
 

data/docs/library-readme.adoc

@@ -0,0 +1,39 @@
+= DocOps Lab: Agent Library
+:doctype: article
+
+This is the *{empty}DocOps Lab agent library* distribution branch.
+It is not intended for direct use as a cloned project.
+
+It is published and consumed automatically by the `docopslab-dev` gem's `labdev:sync:library` Rake task.
+
+
+[[contents]]
+== Contents
+
+`config-packs/`::
+Bundled configuration files for linters and quality tools (Vale, RuboCop, actionlint, etc.), organized by tool name.
+
+`docs/agent/`::
+Generated agent-guidance documents covering roles, skills, missions, and topics for AI agents working on DocOps Lab projects.
+
+`hooks/`::
+Git hook scripts installed by `labdev:init:hooks`.
+
+`scripts/`::
+Utility scripts available to projects via `labdev:sync:scripts`.
+
+`templates/`::
+Boilerplate and sync-cast template files, including `AGENTS.markdown` (the canonical template for project-level `AGENTS.md` files).
+
+`catalog.json`::
+Machine-generated catalog of all files in this library snapshot, including SHA256 checksums and the timestamp of the generating commit.
+
+
+[[usage]]
+== Usage
+
+Projects using `docopslab-dev` fetch this library with:
+
+ bundle exec rake labdev:sync:library
+
+For full documentation, see the https://github.com/DocOps/lab/tree/main/gems/docopslab-dev[docopslab-dev README].