Promote staging to production

.agents/skills/docslime-fill/SKILL.md

@@ -50,6 +50,9 @@ and production learning. Revisit earlier docs when observation changes what the
 - Keep requirements testable and solution-neutral, architecture grounded in real domain
   boundaries, and testing mapped to Given/When/Then behavior.
 - Keep publishing grounded in actual artifacts, gates, promotion, verification, and rollback.
+- Present Semantic Versioning and Conventional Commits as optional publishing practices. Read
+  the existing workflow first; never impose enforcement, rewrite history, or change release
+  automation without explicit team agreement.
 - Keep observability tied to user outcomes as well as system health; never invent telemetry.
 
 ## Steps

docmd.config.json

@@ -2,13 +2,6 @@
   "title": "DocSlime",
   "url": "https://www.docslime.dev",
   "favicon": "/assets/favicon.svg",
-  "logo": {
-    "light": "/assets/images/docslime-wordmark.svg",
-    "dark": "/assets/images/docslime-wordmark-dark.svg",
-    "alt": "DocSlime",
-    "href": "/",
-    "height": "2.5rem"
-  },
   "src": "docs",
   "out": "site",
   "engine": "js",
@@ -22,6 +15,7 @@
   "theme": {
     "name": "default",
     "appearance": "system",
+    "customCss": ["/assets/styles/docslime.css"],
     "codeHighlight": true
   },
   "minify": true,

docs/REQUIREMENTS.md

@@ -31,6 +31,7 @@ discovery, delivery, publication, and production learning.
 | FR-19 | Observability guidance shall connect production system health and user-outcome signals to requirements and discovery while covering telemetry, SLOs, alerts, ownership, and privacy. | Close the product-learning loop |
 | FR-20 | Documentation guidance and first-party docs shall render flowcharts as Mermaid diagrams rather than ASCII art. | Keep diagrams readable and renderable |
 | FR-21 | The scaffold and bundled skills shall describe the docs tree as a project-specific starting template, permit intentional omission of irrelevant product, strategy, or design docs, and preserve experience documentation for developer and agent consumers when useful. | Fit the docs to the project |
+| FR-22 | Publishing guidance shall present Semantic Versioning and Conventional Commits as optional practices, preserve effective existing workflows, and prohibit adding enforcement or rewriting history without explicit team agreement. | Suggest release conventions without imposing workflow |
 
 ## Non-functional requirements
 

docs/assets/styles/docslime.css

@@ -0,0 +1,46 @@
+.sidebar-header h1 a {
+  align-items: center;
+  display: inline-flex;
+  gap: 0.625rem;
+}
+
+.sidebar-header h1 a::before {
+  background: url("../favicon.svg") center / contain no-repeat;
+  content: "";
+  flex: 0 0 2rem;
+  height: 2rem;
+  width: 2rem;
+}
+
+.docslime-hero-wordmark {
+  display: block;
+  height: auto;
+  margin: 0 auto 1rem;
+  width: min(21.375rem, 78vw);
+}
+
+.docslime-hero-wordmark-dark,
+html[data-theme="dark"] .docslime-hero-wordmark-light {
+  display: none;
+}
+
+html[data-theme="dark"] .docslime-hero-wordmark-dark {
+  display: block;
+}
+
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme="light"]) .docslime-hero-wordmark-light {
+    display: none;
+  }
+
+  html:not([data-theme="light"]) .docslime-hero-wordmark-dark {
+    display: block;
+  }
+}
+
+@media (max-width: 640px) {
+  .docslime-hero-wordmark {
+    margin-bottom: 0.75rem;
+    width: min(17rem, 82vw);
+  }
+}

docs/engineering/PUBLISHING.md

@@ -18,6 +18,21 @@ artifact and user-facing behavior are verified.
 | Agent skills | GitHub repository via `npx skills add DecisionNerd/DocSlime` | Repository revision/release |
 | Documentation site | Static `site/` output and configured host | Source commit/deployment |
 
+## Recommended conventions, not mandates
+
+DocSlime recommends considering two complementary standards when they fit a project's release
+model:
+
+- **Semantic Versioning** communicates compatibility through `MAJOR.MINOR.PATCH`. DocSlime
+  uses SemVer for CLI releases because the CLI has a public command and template contract.
+- **Conventional Commits** use `type(scope): description` to make change intent readable by
+  people and release tooling. `fix` commonly corresponds to a patch, `feat` to a minor change,
+  and a declared breaking change to a major change when SemVer applies.
+
+These are suggestions, not requirements. A project should document and preserve an existing
+convention that already works. DocSlime guidance must not introduce commit linting, rewrite
+history, or change version automation without explicit team agreement.
+
 ## Continuous integration
 
 `.github/workflows/ci.yml` validates the CLI, site, agent skills, and branch policy. Only
@@ -73,6 +88,8 @@ host rather than inferred from generated files alone.
 
 ## Official references
 
+- [Semantic Versioning 2.0.0](https://semver.org/)
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
 - [cargo-dist documentation](https://opensource.axo.dev/cargo-dist/)
 - [docmd Quick Start](https://docs.docmd.io/getting-started/quick-start/)
 - [docmd Deployment Overview](https://docs.docmd.io/deployment/)

docs/engineering/TESTING.md

@@ -25,6 +25,7 @@ verified together through the CLI, so the black-box tests double as integration
 | Self-explaining templates | Given a scaffolded tree, When inspected, Then every template carries `<!-- LLM: -->` guidance | `tests/cli.rs::every_template_carries_llm_guidance` |
 | Mermaid flowcharts / FR-20 | Given a scaffolded tree, When diagram guidance and examples are inspected, Then flowcharts use Mermaid and reject ASCII-art guidance | `tests/cli.rs::flowcharts_use_mermaid_in_generated_docs` |
 | Adaptable scaffold / FR-21 | Given a scaffolded tree and bundled skills, When scope guidance is inspected, Then it treats the tree as a starting template and names backend API developer and agent experience as a valid tailored use | `tests/cli.rs::scaffold_and_skills_explain_project_specific_scope` |
+| Optional release conventions / FR-22 | Given a scaffolded tree and publishing skill guidance, When release conventions are inspected, Then Semantic Versioning and Conventional Commits are suggestions and enforcement requires explicit agreement | `tests/cli.rs::suggested_release_conventions_are_optional` |
 | Non-destructive by default / FR-2 | Given an edited file, When `init` re-runs, Then the file is left untouched | `tests/cli.rs::init_skips_existing_files` |
 | Force overwrite / FR-2 | Given an edited file, When `init --force`, Then the template is restored | `tests/cli.rs::init_force_overwrites` |
 | Legacy path safety / FR-17 | Given a filled legacy numbered file, When current `init` or `list` runs, Then the new counterpart is treated as satisfied without duplicating or moving user work | `tests/cli.rs::init_recognizes_legacy_paths`, `list_recognizes_legacy_paths` |

docs/index.md

@@ -5,6 +5,9 @@ image: /assets/images/docslime-hero.png
 ---
 
 ::: hero glow:true
+![DocSlime](/assets/images/docslime-wordmark.svg){.docslime-hero-wordmark .docslime-hero-wordmark-light}
+![DocSlime](/assets/images/docslime-wordmark-dark.svg){.docslime-hero-wordmark .docslime-hero-wordmark-dark}
+
 # Turn your repo into living docs.
 
 DocSlime makes repo knowledge stick. It connects product intent and continuous discovery to

docs/lifecycle.md

@@ -120,6 +120,11 @@ Fill `engineering/PUBLISHING.md` with the real promotion path: artifacts, versio
 gates, deployment verification, and rollback. DocSlime itself promotes `staging` → `main`
 for the site and uses tag-driven releases for the CLI.
 
+As optional defaults, consider Semantic Versioning when public compatibility needs a clear
+`MAJOR.MINOR.PATCH` contract and Conventional Commits when structured change intent would help
+reviews, changelogs, or release automation. Preserve an effective existing workflow; do not
+add enforcement or rewrite history without explicit team agreement.
+
 ### 7. Learn from production
 
 Fill `engineering/OBSERVABILITY.md` to connect system health and user-outcome signals back to

templates/README.md

@@ -58,3 +58,6 @@ Supporting detail lives in subfolders:
   in `docs/` so design and coding agents can load them without duplicate root files.
 - **Close the loop.** Observability should measure both system health and the user outcomes
   named in product, experience, and requirements docs.
+- **Choose release conventions intentionally.** Consider Semantic Versioning and Conventional
+  Commits when they clarify compatibility and change intent, but preserve a team's effective
+  existing workflow and add enforcement only with explicit agreement.

templates/engineering/PUBLISHING.md

@@ -19,6 +19,22 @@ that do not apply. -->
 |---|---|---|---|
 | _Artifact_ | _Registry, environment, store, or host_ | _Tag, digest, release, or commit_ | _Role/team_ |
 
+## Suggested versioning and change history
+
+<!-- LLM: Treat these as optional recommendations, not requirements. First document the
+team's existing versioning, commit, and changelog practices. Suggest Semantic Versioning or
+Conventional Commits only when they would make compatibility and release intent clearer. Do
+not add enforcement, rewrite history, or change release automation without explicit team
+agreement. -->
+
+- Consider **Semantic Versioning** (`MAJOR.MINOR.PATCH`) when an artifact has a public API or
+  compatibility contract: incompatible changes may justify `MAJOR`, backward-compatible
+  features `MINOR`, and backward-compatible fixes `PATCH`.
+- Consider **Conventional Commits** (`type(scope): description`) when human- and
+  machine-readable change history would improve reviews, changelogs, or release automation.
+- Keep the workflow the team already uses when it serves them better. Document the chosen
+  convention and any exceptions; these suggestions do not require enforcement.
+
 ## Build and continuous delivery
 
 <!-- LLM: Add the exact commands and automation that build, sign, package, and publish.
@@ -54,4 +70,6 @@ _How is a harmful release stopped or reversed safely?_
 
 ## Official references
 
+- [Semantic Versioning 2.0.0](https://semver.org/)
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
 - _CI/CD, registry, hosting, package, or documentation publishing reference._

tests/cli.rs

@@ -99,6 +99,32 @@ fn scaffold_and_skills_explain_project_specific_scope() {
     }
 }
 
+#[test]
+fn suggested_release_conventions_are_optional() {
+    let tmp = TempDir::new().unwrap();
+    docslime(tmp.path()).arg("init").assert().success();
+
+    let publishing = fs::read_to_string(tmp.path().join("docs/engineering/PUBLISHING.md")).unwrap();
+    for expected in [
+        "Semantic Versioning",
+        "Conventional Commits",
+        "optional recommendations",
+        "explicit team",
+    ] {
+        assert!(
+            publishing.contains(expected),
+            "engineering/PUBLISHING.md missing {expected}"
+        );
+    }
+
+    let fill_skill = fs::read_to_string(
+        Path::new(env!("CARGO_MANIFEST_DIR")).join(".agents/skills/docslime-fill/SKILL.md"),
+    )
+    .unwrap();
+    assert!(fill_skill.contains("optional publishing practices"));
+    assert!(fill_skill.contains("never impose enforcement"));
+}
+
 #[test]
 fn init_skips_existing_files() {
     let tmp = TempDir::new().unwrap();