diff --git a/docs/_data/nav.yml b/docs/_data/nav.yml new file mode 100644 index 0000000..c89960b --- /dev/null +++ b/docs/_data/nav.yml @@ -0,0 +1,233 @@ +- section: Getting Started + items: + - title: Installation + url: /getting-started/installation/ + expertise: [beginner] + - title: Choose Your Modules + url: /getting-started/choose-your-modules/ + expertise: [beginner, intermediate] + - title: First Steps + url: /getting-started/first-steps/ + expertise: [beginner] + - title: Module Bootstrap Checklist + url: /getting-started/module-bootstrap-checklist/ + expertise: [beginner, intermediate] + - title: "Tutorial: Backlog Quickstart Demo" + url: /getting-started/tutorial-backlog-quickstart-demo/ + expertise: [beginner] + - title: "Tutorial: Backlog Refine with AI IDE" + url: /getting-started/tutorial-backlog-refine-ai-ide/ + expertise: [beginner, intermediate] + - title: "Tutorial: Daily Standup and Sprint Review" + url: /getting-started/tutorial-daily-standup-sprint-review/ + expertise: [beginner, intermediate] + +- section: Bundles + bundles: + - name: Backlog + items: + - title: Overview + url: /bundles/backlog/overview/ + expertise: [beginner, intermediate] + - title: Refinement + url: /bundles/backlog/refinement/ + expertise: [intermediate, advanced] + - title: Delta Commands + url: /bundles/backlog/delta/ + expertise: [intermediate, advanced] + - title: Dependency Analysis + url: /bundles/backlog/dependency-analysis/ + expertise: [intermediate, advanced] + - title: Policy Engine + url: /bundles/backlog/policy-engine/ + expertise: [advanced] + - title: Adapter Patterns + url: /adapters/backlog-adapter-patterns/ + expertise: [advanced] + - name: Project + items: + - title: Overview + url: /bundles/project/overview/ + expertise: [beginner, intermediate] + - title: DevOps Flow + url: /bundles/project/devops-flow/ + expertise: [intermediate, advanced] + - title: Import & Migration + url: /bundles/project/import-migration/ + expertise: [intermediate, advanced] + - name: Codebase + items: + - title: Overview + url: /bundles/codebase/overview/ + expertise: [beginner, intermediate] + - title: Sidecar Validation + url: /bundles/codebase/sidecar-validation/ + expertise: [intermediate, advanced] + - title: Analyze Contracts + url: /bundles/codebase/analyze/ + expertise: [intermediate, advanced] + - title: Drift Detect + url: /bundles/codebase/drift/ + expertise: [intermediate, advanced] + - title: Repro + url: /bundles/codebase/repro/ + expertise: [advanced] + - name: Code Review + items: + - title: Overview + url: /bundles/code-review/overview/ + expertise: [beginner, intermediate] + - title: Run + url: /bundles/code-review/run/ + expertise: [intermediate, advanced] + - title: Ledger + url: /bundles/code-review/ledger/ + expertise: [intermediate, advanced] + - title: Rules + url: /bundles/code-review/rules/ + expertise: [advanced] + - name: Spec + items: + - title: Overview + url: /bundles/spec/overview/ + expertise: [beginner, intermediate] + - title: Validate + url: /bundles/spec/validate/ + expertise: [intermediate, advanced] + - title: Generate Tests + url: /bundles/spec/generate-tests/ + expertise: [intermediate, advanced] + - title: Mock + url: /bundles/spec/mock/ + expertise: [advanced] + - name: Govern + items: + - title: Overview + url: /bundles/govern/overview/ + expertise: [beginner, intermediate] + - title: Enforce + url: /bundles/govern/enforce/ + expertise: [intermediate, advanced] + - title: Patch + url: /bundles/govern/patch/ + expertise: [intermediate, advanced] + +- section: Workflows + items: + - title: Cross-Module Chains + url: /guides/cross-module-chains/ + expertise: [intermediate, advanced] + - title: Daily DevOps Routine + url: /guides/daily-devops-routine/ + expertise: [intermediate] + - title: CI/CD Pipeline + url: /guides/ci-cd-pipeline/ + expertise: [intermediate, advanced] + - title: Brownfield Modernization + url: /guides/brownfield-modernization/ + expertise: [intermediate] + - title: Agile & Scrum Workflows + url: /guides/agile-scrum-workflows/ + expertise: [intermediate] + - title: Command Chains + url: /guides/command-chains/ + expertise: [intermediate, advanced] + - title: Contract Testing + url: /contract-testing-workflow/ + expertise: [advanced] + +- section: Integrations + items: + - title: DevOps Adapter Overview + url: /integrations/devops-adapter-overview/ + expertise: [intermediate] + - title: GitHub Adapter + url: /adapters/github/ + expertise: [intermediate] + - title: Azure DevOps Adapter + url: /adapters/azuredevops/ + expertise: [intermediate] + - title: Integrations Overview + url: /integrations-overview/ + expertise: [intermediate] + +- section: Team & Enterprise + items: + - title: Team Collaboration + url: /team-and-enterprise/team-collaboration/ + expertise: [intermediate] + - title: Agile & Scrum Setup + url: /team-and-enterprise/agile-scrum-setup/ + expertise: [intermediate] + - title: Multi-Repo Setup + url: /team-and-enterprise/multi-repo/ + expertise: [intermediate, advanced] + - title: Enterprise Configuration + url: /team-and-enterprise/enterprise-config/ + expertise: [advanced] + +- section: Authoring + items: + - title: Module Development + url: /authoring/module-development/ + expertise: [advanced] + - title: Adapter Development + url: /authoring/adapter-development/ + expertise: [advanced] + - title: Publishing Modules + url: /authoring/publishing-modules/ + expertise: [advanced] + - title: Module Signing + url: /authoring/module-signing/ + expertise: [advanced] + - title: Custom Registries + url: /authoring/custom-registries/ + expertise: [advanced] + - title: Creating Custom Bridges + url: /authoring/creating-custom-bridges/ + expertise: [advanced] + - title: Extending ProjectBundle + url: /authoring/extending-projectbundle/ + expertise: [advanced] + +- section: Reference + items: + - title: Core vs Modules URL Contract + url: /reference/documentation-url-contract/ + expertise: [advanced] + - title: Reference Documentation + url: /reference/ + expertise: [intermediate, advanced] + - title: Command Reference + url: /reference/commands/ + expertise: [intermediate, advanced] + - title: Thorough Codebase Validation + url: /reference/thorough-codebase-validation/ + expertise: [advanced] + - title: Authentication + url: /reference/authentication/ + expertise: [intermediate, advanced] + - title: Architecture + url: /architecture/ + expertise: [advanced] + - title: Operational Modes + url: /modes/ + expertise: [intermediate] + - title: ProjectBundle Schema + url: /reference/projectbundle-schema/ + expertise: [advanced] + - title: Module Contracts + url: /reference/module-contracts/ + expertise: [advanced] + - title: Module Categories + url: /reference/module-categories/ + expertise: [intermediate] + - title: Dependency Resolution + url: /reference/dependency-resolution/ + expertise: [advanced] + - title: Module Security + url: /reference/module-security/ + expertise: [advanced] + - title: Bridge Registry + url: /reference/bridge-registry/ + expertise: [advanced] diff --git a/docs/_includes/breadcrumbs.html b/docs/_includes/breadcrumbs.html new file mode 100644 index 0000000..496d4ab --- /dev/null +++ b/docs/_includes/breadcrumbs.html @@ -0,0 +1,25 @@ +{% unless page.url == '/' %} + +{% endunless %} diff --git a/docs/_includes/expertise-filter.html b/docs/_includes/expertise-filter.html new file mode 100644 index 0000000..347262b --- /dev/null +++ b/docs/_includes/expertise-filter.html @@ -0,0 +1,7 @@ +
+ + + + + +
diff --git a/docs/_includes/search.html b/docs/_includes/search.html new file mode 100644 index 0000000..44daa3f --- /dev/null +++ b/docs/_includes/search.html @@ -0,0 +1,5 @@ +
+ + Ctrl+K +
+
diff --git a/docs/_includes/sidebar-nav.html b/docs/_includes/sidebar-nav.html new file mode 100644 index 0000000..62f76a5 --- /dev/null +++ b/docs/_includes/sidebar-nav.html @@ -0,0 +1,34 @@ + diff --git a/docs/_includes/theme-toggle.html b/docs/_includes/theme-toggle.html new file mode 100644 index 0000000..101fc3c --- /dev/null +++ b/docs/_includes/theme-toggle.html @@ -0,0 +1,16 @@ + diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 172dbc0..318af42 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -5,6 +5,8 @@ {% seo %} + + @@ -16,84 +18,142 @@ {% endif %} + + @@ -114,6 +174,10 @@ Docs Home Core CLI Modules + + + + {% include theme-toggle.html %} @@ -121,127 +185,20 @@
-
@@ -255,11 +212,23 @@

{{ site.title | escape }}

{{ site.description | escape }}

-
-

{{ site.footer.copyright | escape }}

-
+
+ noldai.com + specfact.com + docs.specfact.io + modules.specfact.io + GitHub + Modules Repo +
+
+

+ © 2025 NOLD AI. All rights reserved. NOLD AI is a registered trademark (EUIPO). +

+ + + diff --git a/docs/adapters/azuredevops.md b/docs/adapters/azuredevops.md index 898e154..142ae04 100644 --- a/docs/adapters/azuredevops.md +++ b/docs/adapters/azuredevops.md @@ -2,6 +2,9 @@ layout: default title: Azure DevOps Adapter permalink: /adapters/azuredevops/ +keywords: [azure-devops, adapter, integration, devops, work-items] +audience: [solo, team, enterprise] +expertise_level: [intermediate] --- # Azure DevOps Adapter diff --git a/docs/adapters/backlog-adapter-patterns.md b/docs/adapters/backlog-adapter-patterns.md index 322e9f6..a12f9b8 100644 --- a/docs/adapters/backlog-adapter-patterns.md +++ b/docs/adapters/backlog-adapter-patterns.md @@ -2,6 +2,9 @@ layout: default title: Backlog Adapter Patterns permalink: /adapters/backlog-adapter-patterns/ +keywords: [adapter, backlog, patterns, integration, devops] +audience: [solo, team, enterprise] +expertise_level: [intermediate] --- # Backlog Adapter Patterns diff --git a/docs/adapters/github.md b/docs/adapters/github.md index 4d8b244..d9acf7a 100644 --- a/docs/adapters/github.md +++ b/docs/adapters/github.md @@ -2,6 +2,9 @@ layout: default title: GitHub Adapter permalink: /adapters/github/ +keywords: [github, adapter, integration, issues, pull-requests] +audience: [solo, team, enterprise] +expertise_level: [intermediate] --- # GitHub Adapter diff --git a/docs/assets/js/filters.js b/docs/assets/js/filters.js new file mode 100644 index 0000000..4523c7f --- /dev/null +++ b/docs/assets/js/filters.js @@ -0,0 +1,72 @@ +(function() { + var pills = document.querySelectorAll('.expertise-pill'); + var countEl = document.querySelector('.expertise-count'); + if (!pills.length) return; + + var stored = 'all'; + try { + stored = localStorage.getItem('specfact-expertise') || 'all'; + } catch (error) { + console.warn('SpecFact expertise filter persistence unavailable.', error); + } + + function applyFilter(level) { + // Update pills + pills.forEach(function(p) { + p.classList.toggle('active', p.getAttribute('data-level') === level); + }); + + var items = document.querySelectorAll('.docs-nav li[data-expertise]'); + var total = items.length; + var visible = 0; + + items.forEach(function(li) { + if (level === 'all') { + li.classList.remove('hidden-by-filter'); + visible++; + } else { + var expertise = (li.getAttribute('data-expertise') || '').split(','); + if (expertise.indexOf(level) !== -1) { + li.classList.remove('hidden-by-filter'); + visible++; + } else { + li.classList.add('hidden-by-filter'); + } + } + }); + + // Hide bundle sections with no visible items + document.querySelectorAll('.docs-nav-bundle').forEach(function(details) { + var visibleItems = details.querySelectorAll('li:not(.hidden-by-filter)'); + if (visibleItems.length === 0 && level !== 'all') { + details.classList.add('hidden-by-filter'); + } else { + details.classList.remove('hidden-by-filter'); + } + }); + + // Update count + if (countEl) { + if (level === 'all') { + countEl.textContent = ''; + } else { + countEl.textContent = visible + ' of ' + total; + } + } + + try { + localStorage.setItem('specfact-expertise', level); + } catch (error) { + console.warn('SpecFact expertise filter persistence unavailable.', error); + } + } + + pills.forEach(function(pill) { + pill.addEventListener('click', function() { + applyFilter(pill.getAttribute('data-level')); + }); + }); + + // Apply stored filter + applyFilter(stored); +})(); diff --git a/docs/assets/js/search-index.json b/docs/assets/js/search-index.json new file mode 100644 index 0000000..87c6768 --- /dev/null +++ b/docs/assets/js/search-index.json @@ -0,0 +1,14 @@ +--- +layout: null +permalink: /assets/js/search-index.json +--- +{% assign pages_with_title = "" | split: "" %}{% for page in site.pages %}{% if page.title %}{% assign pages_with_title = pages_with_title | push: page %}{% endif %}{% endfor %}[{% for page in pages_with_title %} + { + "url": "{{ page.url | relative_url }}", + "title": {{ page.title | jsonify }}, + "keywords": {{ page.keywords | default: "" | jsonify }}, + "audience": {{ page.audience | default: "" | jsonify }}, + "expertise_level": {{ page.expertise_level | default: "" | jsonify }}, + "content": {{ page.content | strip_html | truncatewords: 200 | jsonify }} + }{% unless forloop.last %},{% endunless %}{% endfor %} +] diff --git a/docs/assets/js/search.js b/docs/assets/js/search.js new file mode 100644 index 0000000..31b74b7 --- /dev/null +++ b/docs/assets/js/search.js @@ -0,0 +1,224 @@ +(function() { + var searchRoot = document.querySelector('.docs-search'); + var searchInput = document.querySelector('.docs-search-input'); + var searchResults = document.querySelector('.docs-search-results'); + if (!searchRoot || !searchInput || !searchResults) return; + + var lunrIndex = null; + var searchData = null; + var debounceTimer = null; + var highlightedIndex = -1; + + function setSearchState(message) { + searchResults.textContent = message; + searchResults.style.display = 'block'; + searchResults.classList.add('docs-search-empty'); + } + + function clearSearchState() { + searchResults.classList.remove('docs-search-empty'); + } + + function isSafeRelativeUrl(url) { + return typeof url === 'string' && /^\/(?!\/)/.test(url); + } + + function loadIndex() { + if (lunrIndex) return Promise.resolve(); + if (typeof lunr === 'undefined') { + console.error('SpecFact docs search could not start because lunr is unavailable.'); + setSearchState('Search is temporarily unavailable.'); + return Promise.resolve(); + } + + var indexUrl = searchRoot.getAttribute('data-search-index-url') || '/assets/js/search-index.json'; + return fetch(indexUrl) + .catch(function(error) { + console.error('SpecFact docs search index fetch failed for ' + indexUrl + '.', error); + setSearchState('Search is temporarily unavailable.'); + lunrIndex = null; + searchData = null; + return null; + }) + .then(function(response) { + if (!response) { + return null; + } + return response.json(); + }) + .then(function(data) { + if (!data) { + return; + } + try { + searchData = Array.isArray(data) ? data : []; + lunrIndex = lunr(function() { + this.ref('url'); + this.field('title', { boost: 10 }); + this.field('keywords', { boost: 5 }); + this.field('content'); + searchData.forEach(function(doc) { + this.add({ + url: doc.url, + title: doc.title || '', + keywords: Array.isArray(doc.keywords) ? doc.keywords.join(' ') : (doc.keywords || ''), + content: doc.content || '' + }); + }.bind(this)); + }); + } catch (error) { + console.error('SpecFact docs search index build failed for ' + indexUrl + '.', error); + setSearchState('Search is temporarily unavailable.'); + lunrIndex = null; + searchData = null; + } + }) + .catch(function(error) { + console.error('SpecFact docs search initialization failed for ' + indexUrl + '.', error); + setSearchState('Search is temporarily unavailable.'); + lunrIndex = null; + searchData = null; + }); + } + + function getDoc(url) { + if (!Array.isArray(searchData)) return null; + for (var i = 0; i < searchData.length; i++) { + if (searchData[i].url === url) return searchData[i]; + } + return null; + } + + function createTag(tag) { + var tagEl = document.createElement('span'); + tagEl.className = 'result-tag'; + tagEl.textContent = tag; + return tagEl; + } + + function createResultLink(doc) { + var link = document.createElement('a'); + link.className = 'docs-search-result'; + link.href = isSafeRelativeUrl(doc.url) ? doc.url : '/'; + + var titleEl = document.createElement('div'); + titleEl.className = 'result-title'; + titleEl.textContent = doc.title || ''; + link.appendChild(titleEl); + + var snippetEl = document.createElement('div'); + snippetEl.className = 'result-snippet'; + snippetEl.textContent = ((doc.content || '').substring(0, 120) + '...').trim(); + link.appendChild(snippetEl); + + var audience = Array.isArray(doc.audience) ? doc.audience : []; + var expertise = Array.isArray(doc.expertise_level) ? doc.expertise_level : []; + var tags = audience.concat(expertise).filter(Boolean); + if (tags.length) { + var tagsEl = document.createElement('div'); + tagsEl.className = 'result-tags'; + tags.forEach(function(tag) { + tagsEl.appendChild(createTag(tag)); + }); + link.appendChild(tagsEl); + } + + return link; + } + + function renderResults(results) { + highlightedIndex = -1; + clearSearchState(); + if (results.length === 0) { + setSearchState('No results found'); + return; + } + + searchResults.innerHTML = ''; + results.slice(0, 10).forEach(function(result) { + var doc = getDoc(result.ref); + if (!doc) return; + searchResults.appendChild(createResultLink(doc)); + }); + + if (!searchResults.children.length) { + setSearchState('No results found'); + return; + } + + searchResults.style.display = 'block'; + } + + function doSearch(query) { + if (!lunrIndex || query.length < 2) { + clearSearchState(); + searchResults.style.display = 'none'; + return; + } + try { + renderResults(lunrIndex.search(query + '*')); + } catch (error) { + try { + renderResults(lunrIndex.search(query)); + } catch (fallbackError) { + console.error('SpecFact docs search query failed.', fallbackError); + setSearchState('Search is temporarily unavailable.'); + } + } + } + + function updateHighlight(items) { + items.forEach(function(item, i) { + item.classList.toggle('highlighted', i === highlightedIndex); + }); + } + + searchInput.addEventListener('focus', function() { + loadIndex().then(function() { + clearSearchState(); + }); + }); + + searchInput.addEventListener('input', function() { + clearTimeout(debounceTimer); + var query = searchInput.value.trim(); + debounceTimer = setTimeout(function() { + doSearch(query); + }, 150); + }); + + searchInput.addEventListener('keydown', function(e) { + var items = searchResults.querySelectorAll('.docs-search-result'); + if (e.key === 'ArrowDown') { + e.preventDefault(); + highlightedIndex = Math.min(highlightedIndex + 1, items.length - 1); + updateHighlight(items); + } else if (e.key === 'ArrowUp') { + e.preventDefault(); + highlightedIndex = Math.max(highlightedIndex - 1, 0); + updateHighlight(items); + } else if (e.key === 'Enter' && highlightedIndex >= 0 && items[highlightedIndex]) { + e.preventDefault(); + items[highlightedIndex].click(); + } else if (e.key === 'Escape') { + clearSearchState(); + searchResults.style.display = 'none'; + searchInput.blur(); + } + }); + + document.addEventListener('click', function(e) { + if (!e.target.closest('.docs-search')) { + clearSearchState(); + searchResults.style.display = 'none'; + } + }); + + document.addEventListener('keydown', function(e) { + if ((e.ctrlKey || e.metaKey) && e.key === 'k') { + e.preventDefault(); + searchInput.focus(); + searchInput.select(); + } + }); +})(); diff --git a/docs/assets/js/theme.js b/docs/assets/js/theme.js new file mode 100644 index 0000000..444fb97 --- /dev/null +++ b/docs/assets/js/theme.js @@ -0,0 +1,26 @@ +// Theme initialization - runs in to prevent FOUC +(function() { + var stored = localStorage.getItem('specfact-theme'); + var theme = stored || (window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'); + document.documentElement.setAttribute('data-theme', theme); +})(); + +function toggleTheme() { + var current = document.documentElement.getAttribute('data-theme') || 'dark'; + var next = current === 'dark' ? 'light' : 'dark'; + document.documentElement.setAttribute('data-theme', next); + localStorage.setItem('specfact-theme', next); + + // Update toggle button icons + var sunIcon = document.querySelector('.theme-toggle .icon-sun'); + var moonIcon = document.querySelector('.theme-toggle .icon-moon'); + if (sunIcon && moonIcon) { + sunIcon.style.display = next === 'dark' ? 'none' : 'block'; + moonIcon.style.display = next === 'dark' ? 'block' : 'none'; + } + + // Re-render mermaid diagrams if available + if (typeof rerenderMermaid === 'function') { + rerenderMermaid(next); + } +} diff --git a/docs/assets/main.scss b/docs/assets/main.scss index e6f0ade..7fff8e9 100644 --- a/docs/assets/main.scss +++ b/docs/assets/main.scss @@ -1,215 +1,385 @@ --- # Jekyll frontmatter required for SCSS processing -# Explicit permalink to prevent Jekyll from applying default permalink pattern permalink: /assets/main.css --- @import "minima"; -// Custom styling for SpecFact CLI documentation -// These styles override minima theme defaults - +// ============================================================================ +// Baseline theme variables +// ============================================================================ :root { - /* SpecFact.io color scheme - Documentation theme */ - --primary-color: #64ffda; - --primary-hover: #7affeb; + --primary-color: #57e6c4; + --primary-hover: #6eefd3; + --text-color: #ccd6f6; + --text-light: #8892b0; + --text-muted: #495670; + --bg-color: #0a192f; + --bg-light: #112240; + --bg-alt: #1d2d50; + --border-color: rgba(87, 230, 196, 0.12); + --border-hover: rgba(87, 230, 196, 0.3); + --code-bg: #1d2d50; + --link-color: #57e6c4; + --link-hover: #6eefd3; + --search-bg: #1d2d50; + --search-border: rgba(87, 230, 196, 0.2); + --card-bg: #112240; + --card-border: rgba(87, 230, 196, 0.15); + --breadcrumb-color: #8892b0; + --badge-bg: rgba(87, 230, 196, 0.12); + --badge-color: #57e6c4; + --filter-bg: #1d2d50; + color-scheme: dark; +} + +// ============================================================================ +// Dark theme (default) +// ============================================================================ +[data-theme="dark"] { + --primary-color: #57e6c4; + --primary-hover: #6eefd3; --text-color: #ccd6f6; --text-light: #8892b0; --text-muted: #495670; --bg-color: #0a192f; --bg-light: #112240; --bg-alt: #1d2d50; - --border-color: rgba(100, 255, 218, 0.1); - --border-hover: rgba(100, 255, 218, 0.3); + --border-color: rgba(87, 230, 196, 0.12); + --border-hover: rgba(87, 230, 196, 0.3); --code-bg: #1d2d50; - --link-color: #64ffda; - --link-hover: #7affeb; + --link-color: #57e6c4; + --link-hover: #6eefd3; + --search-bg: #1d2d50; + --search-border: rgba(87, 230, 196, 0.2); + --card-bg: #112240; + --card-border: rgba(87, 230, 196, 0.15); + --breadcrumb-color: #8892b0; + --badge-bg: rgba(87, 230, 196, 0.12); + --badge-color: #57e6c4; + --filter-bg: #1d2d50; + color-scheme: dark; +} + +// ============================================================================ +// Light theme +// ============================================================================ +[data-theme="light"] { + --primary-color: #0d9488; + --primary-hover: #0f766e; + --text-color: #1a1a2e; + --text-light: #475569; + --text-muted: #94a3b8; + --bg-color: #ffffff; + --bg-light: #f8fafc; + --bg-alt: #f1f5f9; + --border-color: #e2e8f0; + --border-hover: #cbd5e1; + --code-bg: #f1f5f9; + --link-color: #0d9488; + --link-hover: #0f766e; + --search-bg: #ffffff; + --search-border: #cbd5e1; + --card-bg: #f8fafc; + --card-border: #e2e8f0; + --breadcrumb-color: #64748b; + --badge-bg: #f0fdfa; + --badge-color: #0d9488; + --filter-bg: #f1f5f9; + color-scheme: light; +} + +// System preference fallback (when no data-theme attribute) +@media (prefers-color-scheme: light) { + :root:not([data-theme]) { + --primary-color: #0d9488; + --primary-hover: #0f766e; + --text-color: #1a1a2e; + --text-light: #475569; + --text-muted: #94a3b8; + --bg-color: #ffffff; + --bg-light: #f8fafc; + --bg-alt: #f1f5f9; + --border-color: #e2e8f0; + --border-hover: #cbd5e1; + --code-bg: #f1f5f9; + --link-color: #0d9488; + --link-hover: #0f766e; + --search-bg: #ffffff; + --search-border: #cbd5e1; + --card-bg: #f8fafc; + --card-border: #e2e8f0; + --breadcrumb-color: #64748b; + --badge-bg: #f0fdfa; + --badge-color: #0d9488; + --filter-bg: #f1f5f9; + color-scheme: light; + } +} + +@media (prefers-color-scheme: dark) { + :root:not([data-theme]) { + --primary-color: #57e6c4; + --primary-hover: #6eefd3; + --text-color: #ccd6f6; + --text-light: #8892b0; + --text-muted: #495670; + --bg-color: #0a192f; + --bg-light: #112240; + --bg-alt: #1d2d50; + --border-color: rgba(87, 230, 196, 0.12); + --border-hover: rgba(87, 230, 196, 0.3); + --code-bg: #1d2d50; + --link-color: #57e6c4; + --link-hover: #6eefd3; + --search-bg: #1d2d50; + --search-border: rgba(87, 230, 196, 0.2); + --card-bg: #112240; + --card-border: rgba(87, 230, 196, 0.15); + --breadcrumb-color: #8892b0; + --badge-bg: rgba(87, 230, 196, 0.12); + --badge-color: #57e6c4; + --filter-bg: #1d2d50; + color-scheme: dark; + } +} + +// ============================================================================ +// Themed scrollbars +// ============================================================================ +* { + scrollbar-width: thin; + scrollbar-color: var(--border-hover) var(--bg-light); } -// Override body styles with !important to ensure they apply +::-webkit-scrollbar { width: 8px; height: 8px; } +::-webkit-scrollbar-track { background: var(--bg-light); } +::-webkit-scrollbar-thumb { + background: var(--border-hover); + border-radius: 4px; + &:hover { background: var(--text-muted); } +} + +// ============================================================================ +// Base styles +// ============================================================================ body { font-family: 'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif !important; line-height: 1.7 !important; color: var(--text-color) !important; background-color: var(--bg-color) !important; -webkit-font-smoothing: antialiased; + transition: background-color 0.2s, color 0.2s; } -// Header styling +// ============================================================================ +// Header +// ============================================================================ .site-header { - border-bottom: 2px solid var(--border-color); + border-bottom: 1px solid var(--border-color); background-color: var(--bg-light); - padding: 1rem 0; - + padding: 0.75rem 0; + transition: background-color 0.2s; + .site-title { - font-size: 1.5rem; + font-size: 1.35rem; font-weight: 700; color: var(--primary-color); text-decoration: none; - - &:hover { - color: var(--primary-hover); - } + &:hover { color: var(--primary-hover); } } - + .site-nav { + display: flex; + align-items: center; + .page-link { color: var(--text-color); font-weight: 500; margin: 0 0.5rem; text-decoration: none; transition: color 0.2s; - - &:hover { - color: var(--primary-color); - } + &:hover { color: var(--primary-color); } } } } -// Main content area - minima uses .page-content with .wrapper +// GitHub link in header +.github-link { + display: inline-flex; + align-items: center; + color: var(--text-color); + margin-left: 0.75rem; + padding: 0.4rem; + border: 1px solid var(--border-color); + border-radius: 0.375rem; + transition: color 0.2s, border-color 0.2s; + &:hover { + color: var(--primary-color); + border-color: var(--primary-color); + } + svg { width: 18px; height: 18px; fill: currentColor; } +} + +// Theme toggle button +.theme-toggle { + background: none; + border: 1px solid var(--border-color); + border-radius: 0.375rem; + padding: 0.35rem 0.5rem; + cursor: pointer; + color: var(--text-light); + display: inline-flex; + align-items: center; + margin-left: 0.5rem; + transition: color 0.2s, border-color 0.2s; + + &:hover { + color: var(--primary-color); + border-color: var(--primary-color); + } + + svg { display: block; } +} + +// Show correct icon per theme +[data-theme="dark"] .theme-toggle .icon-sun { display: none; } +[data-theme="dark"] .theme-toggle .icon-moon { display: block; } +[data-theme="light"] .theme-toggle .icon-sun { display: block; } +[data-theme="light"] .theme-toggle .icon-moon { display: none; } + +// ============================================================================ +// Page content area +// ============================================================================ .page-content { padding: 2rem 0; color: var(--text-color) !important; background-color: var(--bg-color) !important; + transition: background-color 0.2s; } -// Ensure all text elements have proper color .page-content, -.page-content * { - color: inherit; -} +.page-content * { color: inherit; } -// Page content styling (scoped to docs-content to avoid conflicts) +// ============================================================================ +// Docs content area +// ============================================================================ .docs-content { - padding: 2rem 0; + flex: 1 1 0%; + min-width: 0; + max-width: 900px; + padding: 1.5rem 2rem; + overflow-wrap: anywhere; + word-break: break-word; color: var(--text-color) !important; background-color: var(--bg-color) !important; - + h1 { - font-size: 2.5rem; + font-size: 2.25rem; font-weight: 800; margin-bottom: 1rem; color: var(--text-color) !important; - border-bottom: 3px solid var(--primary-color); + border-bottom: 2px solid var(--primary-color); padding-bottom: 0.5rem; } - + h2 { - font-size: 2rem; + font-size: 1.75rem; font-weight: 700; margin-top: 2rem; - margin-bottom: 1rem; + margin-bottom: 0.75rem; color: var(--text-color) !important; } - + h3 { - font-size: 1.5rem; + font-size: 1.35rem; font-weight: 600; margin-top: 1.5rem; - margin-bottom: 0.75rem; + margin-bottom: 0.5rem; color: var(--text-color) !important; } - + h4 { - font-size: 1.25rem; + font-size: 1.15rem; font-weight: 600; margin-top: 1rem; margin-bottom: 0.5rem; color: var(--text-color) !important; } - - p { - margin-bottom: 1rem; - color: var(--text-color) !important; - } - - // Ensure all text in docs-content is visible - * { - color: inherit; - } - - // Links + + p { margin-bottom: 1rem; color: var(--text-color) !important; } + * { color: inherit; } + a { color: var(--link-color); text-decoration: none; font-weight: 500; transition: color 0.2s; - - &:hover { - color: var(--link-hover); - text-decoration: underline; - } + &:hover { color: var(--link-hover); text-decoration: underline; } } - - // Lists + ul, ol { margin-bottom: 1rem; padding-left: 2rem; color: var(--text-color) !important; - li { - margin-bottom: 0.5rem; + margin-bottom: 0.4rem; color: var(--text-color) !important; - a { color: var(--link-color) !important; - - &:hover { - color: var(--link-hover) !important; - } + &:hover { color: var(--link-hover) !important; } } } } - - // Tables (common in command reference) + + // Tables table { width: 100%; border-collapse: collapse; margin: 1.5rem 0; background-color: var(--bg-color) !important; - + border: 1px solid var(--border-color); + border-radius: 0.375rem; + overflow-x: auto; + display: block; + th, td { - padding: 0.75rem; - border: 1px solid var(--border-color); + padding: 0.6rem 0.75rem; + border-bottom: 1px solid var(--border-color); color: var(--text-color) !important; + text-align: left; } - + th { background-color: var(--bg-light) !important; font-weight: 600; + font-size: 0.9rem; color: var(--text-color) !important; } - - tr { - background-color: var(--bg-color) !important; - } - - tr:nth-child(even) { - background-color: var(--bg-light) !important; - } + + tr { background-color: var(--bg-color) !important; } + tr:nth-child(even) { background-color: var(--bg-light) !important; } } - - // Code blocks - Rouge syntax highlighting + + // Code blocks .highlighter-rouge { background-color: var(--code-bg) !important; border: 1px solid var(--border-color); - border-radius: 0.5rem; + border-left: 3px solid var(--primary-color); + border-radius: 0.375rem; margin-bottom: 1rem; font-family: 'JetBrains Mono', 'Fira Code', monospace !important; - + .highlight { background-color: var(--code-bg) !important; - pre { background-color: var(--code-bg) !important; border: none; - border-radius: 0.5rem; + border-radius: 0.375rem; padding: 1rem; overflow-x: auto; margin: 0; color: var(--text-color) !important; - code { background-color: transparent !important; padding: 0; @@ -220,18 +390,17 @@ body { } } } - - // Code blocks (fallback for non-Rouge) + pre { background-color: var(--code-bg) !important; border: 1px solid var(--border-color); - border-radius: 0.5rem; + border-left: 3px solid var(--primary-color); + border-radius: 0.375rem; padding: 1rem; overflow-x: auto; margin-bottom: 1rem; color: var(--text-color) !important; font-family: 'JetBrains Mono', 'Fira Code', monospace !important; - code { background-color: transparent !important; padding: 0; @@ -240,282 +409,540 @@ body { font-family: 'JetBrains Mono', 'Fira Code', monospace !important; } } - - // Inline code + code { background-color: var(--code-bg) !important; - padding: 0.2rem 0.4rem; + padding: 0.15rem 0.35rem; border-radius: 0.25rem; - font-size: 0.9em; + font-size: 0.88em; border: 1px solid var(--border-color); color: var(--text-color) !important; font-family: 'JetBrains Mono', 'Fira Code', monospace !important; } - - // Rouge syntax highlighting spans - dark theme colors for readability + + // Rouge dark syntax highlighting .highlight { - span { - background-color: transparent !important; - color: var(--text-color) !important; - } - - // Syntax highlighting colors (dark theme optimized) - .c { color: #8892b0 !important; } // Comments - muted gray-blue - .k { color: #ff6b9d !important; } // Keywords - pink/red - .l { color: #64ffda !important; } // Literals - cyan - .n { color: var(--text-color) !important; } // Names - .o { color: #ff6b9d !important; } // Operators - pink - .p { color: #ccd6f6 !important; } // Punctuation - light text - .cm { color: #8892b0 !important; } // Comment multiline - .cp { color: #8892b0 !important; } // Comment preproc - .c1 { color: #8892b0 !important; } // Comment single - .cs { color: #8892b0 !important; } // Comment special - .gd { color: #ff6b9d !important; } // Generic deleted - .ge { font-style: italic !important; } // Generic emph - .gr { color: #ff6b9d !important; } // Generic error - .gh { color: var(--text-color) !important; font-weight: bold !important; } // Generic heading - .gi { color: #64ffda !important; } // Generic inserted - cyan - .go { color: #8892b0 !important; } // Generic output - .gp { color: #8892b0 !important; } // Generic prompt - .gs { font-weight: bold !important; } // Generic strong - .gu { color: var(--text-color) !important; font-weight: bold !important; } // Generic subheading - .gt { color: #ff6b9d !important; } // Generic traceback - .kc { color: #64ffda !important; } // Keyword constant - cyan - .kd { color: #ff6b9d !important; } // Keyword declaration - pink - .kn { color: #ff6b9d !important; } // Keyword namespace - .kp { color: #ff6b9d !important; } // Keyword pseudo - .kr { color: #ff6b9d !important; } // Keyword reserved - .kt { color: #ff6b9d !important; } // Keyword type - .ld { color: #64ffda !important; } // Literal date - cyan - .m { color: #64ffda !important; } // Literal number - cyan - .s { color: #a8e6cf !important; } // Literal string - light green - .na { color: #64ffda !important; } // Name attribute - cyan - .nb { color: #64ffda !important; } // Name builtin - cyan - .nc { color: #c792ea !important; } // Name class - purple - .no { color: #64ffda !important; } // Name constant - cyan - .nd { color: #c792ea !important; } // Name decorator - purple - .ni { color: #c792ea !important; } // Name entity - purple - .ne { color: #ff6b9d !important; font-weight: bold !important; } // Name exception - .nf { color: #c792ea !important; } // Name function - purple - .nl { color: #64ffda !important; } // Name label - cyan - .nn { color: var(--text-color) !important; } // Name namespace - .nx { color: var(--text-color) !important; } // Name other - .py { color: var(--text-color) !important; } // Name property - .nt { color: #64ffda !important; } // Name tag - cyan (YAML keys) - .nv { color: #ffd93d !important; } // Name variable - yellow - .ow { color: #ff6b9d !important; } // Operator word - .w { color: #8892b0 !important; } // Text whitespace - .mf { color: #64ffda !important; } // Literal number float - .mh { color: #64ffda !important; } // Literal number hex - .mi { color: #64ffda !important; } // Literal number integer - .mo { color: #64ffda !important; } // Literal number oct - .sb { color: #a8e6cf !important; } // Literal string backtick - .sc { color: #a8e6cf !important; } // Literal string char - .sd { color: #8892b0 !important; } // Literal string doc - .s2 { color: #a8e6cf !important; } // Literal string double - .se { color: #a8e6cf !important; } // Literal string escape - .sh { color: #a8e6cf !important; } // Literal string heredoc - .si { color: #a8e6cf !important; } // Literal string interpol - .sx { color: #a8e6cf !important; } // Literal string other - .sr { color: #a8e6cf !important; } // Literal string regex - .s1 { color: #a8e6cf !important; } // Literal string single - .ss { color: #a8e6cf !important; } // Literal string symbol - .bp { color: var(--text-color) !important; } // Name builtin pseudo - .vc { color: #ffd93d !important; } // Name variable class - yellow - .vg { color: #ffd93d !important; } // Name variable global - yellow - .vi { color: #ffd93d !important; } // Name variable instance - yellow - .il { color: #64ffda !important; } // Literal number integer long - } - - // Blockquotes + span { background-color: transparent !important; } + } + blockquote { - border-left: 4px solid var(--primary-color); + border-left: 3px solid var(--primary-color); padding-left: 1rem; margin: 1rem 0; color: var(--text-light); font-style: italic; } - - // Horizontal rules - hr { - border: none; - border-top: 2px solid var(--border-color); - margin: 2rem 0; - } - - // Emoji and special elements - .emoji { - font-size: 1.2em; - } - - // Primary callout sections + + hr { border: none; border-top: 1px solid var(--border-color); margin: 2rem 0; } + .primary { background-color: var(--bg-light); - border-left: 4px solid var(--primary-color); + border-left: 3px solid var(--primary-color); padding: 1rem; margin: 1.5rem 0; border-radius: 0.25rem; } } -// Docs layout with left navigation +// ============================================================================ +// Dark theme syntax highlighting +// ============================================================================ +[data-theme="dark"] .docs-content .highlight { + .c, .cm, .cp, .c1, .cs { color: #8892b0 !important; } + .k, .kd, .kn, .kp, .kr, .kt { color: #ff6b9d !important; } + .o, .ow { color: #ff6b9d !important; } + .l, .ld, .m, .mf, .mh, .mi, .mo, .il { color: #57e6c4 !important; } + .kc { color: #57e6c4 !important; } + .s, .sb, .sc, .s2, .se, .sh, .si, .sx, .sr, .s1, .ss { color: #a8e6cf !important; } + .sd { color: #8892b0 !important; } + .n { color: #ccd6f6 !important; } + .na, .nb, .no, .nl, .nt { color: #57e6c4 !important; } + .nc, .nd, .ni, .nf { color: #c792ea !important; } + .ne { color: #ff6b9d !important; font-weight: bold !important; } + .nv, .vc, .vg, .vi { color: #ffd93d !important; } + .nn, .nx, .py, .bp { color: #ccd6f6 !important; } + .p { color: #ccd6f6 !important; } + .w { color: #8892b0 !important; } + .gd, .gr, .gt { color: #ff6b9d !important; } + .gi { color: #57e6c4 !important; } + .ge { font-style: italic !important; } + .gs { font-weight: bold !important; } + .gh, .gu { color: #ccd6f6 !important; font-weight: bold !important; } + .go, .gp { color: #8892b0 !important; } +} + +// ============================================================================ +// Light theme syntax highlighting +// ============================================================================ +[data-theme="light"] .docs-content .highlight { + .c, .cm, .cp, .c1, .cs { color: #6a737d !important; } + .k, .kd, .kn, .kp, .kr, .kt { color: #d73a49 !important; } + .o, .ow { color: #d73a49 !important; } + .l, .ld, .m, .mf, .mh, .mi, .mo, .il { color: #005cc5 !important; } + .kc { color: #005cc5 !important; } + .s, .sb, .sc, .s2, .se, .sh, .si, .sx, .sr, .s1, .ss { color: #032f62 !important; } + .sd { color: #6a737d !important; } + .n { color: #24292e !important; } + .na { color: #005cc5 !important; } + .nb { color: #005cc5 !important; } + .nc, .nd, .ni, .nf { color: #6f42c1 !important; } + .ne { color: #d73a49 !important; font-weight: bold !important; } + .nl, .nt { color: #22863a !important; } + .no { color: #005cc5 !important; } + .nv, .vc, .vg, .vi { color: #e36209 !important; } + .nn, .nx, .py, .bp { color: #24292e !important; } + .p { color: #24292e !important; } + .w { color: #6a737d !important; } + .gd, .gr, .gt { color: #d73a49 !important; } + .gi { color: #22863a !important; } + .ge { font-style: italic !important; } + .gs { font-weight: bold !important; } + .gh, .gu { color: #24292e !important; font-weight: bold !important; } + .go, .gp { color: #6a737d !important; } +} + +// ============================================================================ +// Layout — override minima's narrow .wrapper +// ============================================================================ + +// Minima default is max-width ~740px — far too narrow for a sidebar + content layout. +// Override globally and let each section control its own constraints. +.wrapper { + max-width: none !important; + padding-right: 1.5rem !important; + padding-left: 1.5rem !important; +} + .wrapper.docs-layout { - max-width: 1200px; - margin: 0 auto; - padding: 2rem 1rem; + max-width: 100%; + margin: 0; + padding: 0; display: flex; - gap: 2rem; - align-items: flex-start; + gap: 0; + align-items: stretch; + min-height: calc(100vh - 8rem); } +// ============================================================================ +// Sidebar +// ============================================================================ .docs-sidebar { - flex: 0 0 260px; + flex: 0 0 270px; + min-width: 270px; border-right: 1px solid var(--border-color); background-color: var(--bg-light); - padding: 1.5rem 1rem; + padding: 1.25rem 1rem; position: sticky; - top: 4rem; - max-height: calc(100vh - 4rem); + top: 0; + height: 100vh; overflow-y: auto; + scrollbar-width: thin; + transition: background-color 0.2s; } .docs-sidebar-title { - font-size: 1.25rem; + font-size: 1.1rem; font-weight: 700; - margin: 0 0 1rem 0; -} - -.docs-sidebar-title a { - color: var(--primary-color); - text-decoration: none; -} - -.docs-sidebar-title a:hover { - color: var(--primary-hover); - text-decoration: underline; + margin: 0 0 0.75rem 0; + a { + color: var(--primary-color); + text-decoration: none; + &:hover { color: var(--primary-hover); text-decoration: underline; } + } } .docs-nav { - font-size: 0.95rem; + font-size: 0.875rem; + line-height: 1.5; } .docs-nav-section { font-weight: 600; - margin: 1rem 0 0.5rem 0; + margin: 1.25rem 0 0.35rem 0; color: var(--text-light); text-transform: uppercase; - letter-spacing: 0.05em; - font-size: 0.8rem; + letter-spacing: 0.06em; + font-size: 0.7rem; } .docs-nav ul { list-style: none; - margin: 0 0 0.5rem 0; + margin: 0 0 0.25rem 0; padding-left: 0; } .docs-nav li { - margin-bottom: 0.35rem; + margin-bottom: 0.15rem; } .docs-nav a { color: var(--text-color); text-decoration: none; + display: block; + padding: 0.2rem 0.5rem; + border-radius: 0.25rem; + transition: color 0.15s, background-color 0.15s; + &:hover { + color: var(--primary-color); + background-color: var(--bg-alt); + } + &.active { + color: var(--primary-color); + background-color: var(--bg-alt); + font-weight: 600; + border-left: 2px solid var(--primary-color); + padding-left: calc(0.5rem - 2px); + } } -.docs-nav a:hover { - color: var(--primary-color); - text-decoration: underline; +// Bundle collapsible sections +.docs-nav-bundle { + margin-bottom: 0.25rem; + + summary { + font-weight: 600; + color: var(--text-color); + cursor: pointer; + padding: 0.3rem 0.5rem; + border-radius: 0.25rem; + list-style: none; + display: flex; + align-items: center; + gap: 0.35rem; + transition: color 0.15s; + + &:hover { color: var(--primary-color); } + + &::before { + content: ''; + display: inline-block; + width: 0; + height: 0; + border-left: 5px solid var(--text-light); + border-top: 4px solid transparent; + border-bottom: 4px solid transparent; + transition: transform 0.2s; + } + + &::-webkit-details-marker { display: none; } + } + + &[open] > summary::before { + transform: rotate(90deg); + } + + ul { + padding-left: 1rem; + margin-top: 0.15rem; + } } -.docs-content { - flex: 1 1 auto; - min-width: 0; +// ============================================================================ +// Search +// ============================================================================ +.docs-search { + position: relative; + margin-bottom: 0.75rem; } -// Footer styling -.site-footer { - border-top: 2px solid var(--border-color); +.docs-search-input { + width: 100%; + padding: 0.45rem 0.65rem; + font-size: 0.8rem; + font-family: inherit; + background-color: var(--search-bg); + color: var(--text-color); + border: 1px solid var(--search-border); + border-radius: 0.375rem; + outline: none; + transition: border-color 0.2s; + box-sizing: border-box; + + &::placeholder { color: var(--text-muted); } + &:focus { border-color: var(--primary-color); } +} + +.docs-search-shortcut { + position: absolute; + right: 0.5rem; + top: 50%; + transform: translateY(-50%); + font-size: 0.65rem; + color: var(--text-muted); + border: 1px solid var(--border-color); + border-radius: 0.2rem; + padding: 0.1rem 0.3rem; + pointer-events: none; +} + +.docs-search-results { + position: absolute; + top: 100%; + left: 0; + right: 0; background-color: var(--bg-light); - padding: 2rem 0; - margin-top: 3rem; + border: 1px solid var(--border-color); + border-radius: 0.375rem; + margin-top: 0.25rem; + max-height: 320px; + overflow-y: auto; + z-index: 100; + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); + display: none; +} + +.docs-search-result { + padding: 0.5rem 0.65rem; + cursor: pointer; + border-bottom: 1px solid var(--border-color); + transition: background-color 0.1s; + + &:last-child { border-bottom: none; } + &:hover, &.highlighted { background-color: var(--bg-alt); } + + .result-title { + font-weight: 600; + font-size: 0.85rem; + color: var(--text-color); + margin-bottom: 0.15rem; + } + + .result-snippet { + font-size: 0.75rem; + color: var(--text-light); + line-height: 1.4; + } + + .result-tags { + display: flex; + gap: 0.25rem; + margin-top: 0.25rem; + flex-wrap: wrap; + } + + .result-tag { + font-size: 0.6rem; + padding: 0.1rem 0.35rem; + border-radius: 0.2rem; + background-color: var(--badge-bg); + color: var(--badge-color); + font-weight: 500; + } +} + +.docs-search-empty { + padding: 0.75rem; text-align: center; + color: var(--text-muted); + font-size: 0.8rem; +} + +// ============================================================================ +// Expertise filter +// ============================================================================ +.docs-expertise-filter { + display: flex; + align-items: center; + gap: 0.35rem; + margin-bottom: 0.75rem; + flex-wrap: wrap; +} + +.expertise-pill { + font-size: 0.65rem; + padding: 0.2rem 0.5rem; + border-radius: 1rem; + border: 1px solid var(--border-color); + background: none; color: var(--text-light); - font-size: 0.9rem; - - .footer-heading { + cursor: pointer; + font-family: inherit; + transition: all 0.15s; + + &:hover { border-color: var(--primary-color); color: var(--primary-color); } + + &.active { + background-color: var(--primary-color); + color: var(--bg-color); + border-color: var(--primary-color); font-weight: 600; - margin-bottom: 0.5rem; - color: var(--text-color); } - +} + +.expertise-count { + font-size: 0.6rem; + color: var(--text-muted); + margin-left: auto; +} + +// ============================================================================ +// Breadcrumbs +// ============================================================================ +.docs-breadcrumbs { + font-size: 0.8rem; + color: var(--breadcrumb-color); + margin-bottom: 1.25rem; + padding-bottom: 0.5rem; + border-bottom: 1px solid var(--border-color); + + a { + color: var(--breadcrumb-color); + text-decoration: none; + &:hover { color: var(--primary-color); text-decoration: underline; } + } + + .separator { + margin: 0 0.35rem; + color: var(--text-muted); + } + + .current { color: var(--text-color); font-weight: 500; } +} + +// ============================================================================ +// Find Your Path cards +// ============================================================================ +.path-cards { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); + gap: 1rem; + margin: 1.5rem 0 2rem; +} + +.path-card { + background-color: var(--card-bg); + border: 1px solid var(--card-border); + border-radius: 0.5rem; + padding: 1.25rem; + transition: border-color 0.2s, box-shadow 0.2s; + + &:hover { + border-color: var(--primary-color); + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); + } + + h3 { + font-size: 1rem; + font-weight: 700; + margin: 0 0 0.5rem 0; + color: var(--primary-color) !important; + border: none !important; + padding: 0 !important; + } + + p { + font-size: 0.85rem; + color: var(--text-light) !important; + margin-bottom: 0.75rem; + } + + ul { + list-style: none; + padding-left: 0; + margin: 0; + li { + margin-bottom: 0.3rem; + font-size: 0.85rem; + a { font-weight: 500; } + } + } +} + +// ============================================================================ +// Footer +// ============================================================================ +.site-footer { + border-top: 1px solid var(--border-color); + background-color: var(--bg-light); + padding: 1.5rem 0; + margin-top: 0; + text-align: center; + color: var(--text-light); + font-size: 0.85rem; + transition: background-color 0.2s; + .footer-col-wrapper { display: flex; justify-content: center; flex-wrap: wrap; gap: 2rem; } - + a { color: var(--link-color); - - &:hover { - color: var(--link-hover); - } + text-decoration: none; + &:hover { color: var(--link-hover); text-decoration: underline; } + } + + .footer-links { + display: flex; + justify-content: center; + gap: 1.5rem; + flex-wrap: wrap; + margin-top: 0.75rem; + } + + .footer-trademark { + font-size: 0.72rem; + color: var(--text-muted); + margin-top: 0.75rem; + max-width: 700px; + margin-left: auto; + margin-right: auto; + line-height: 1.5; + } + + .footer-separator { + border: none; + border-top: 1px solid var(--border-color); + margin: 1rem auto; + max-width: 400px; } } -// Responsive design +// ============================================================================ +// Responsive +// ============================================================================ @media screen and (max-width: 768px) { - .docs-layout { - padding: 1.5rem 1rem; + .wrapper.docs-layout { flex-direction: column; } .docs-sidebar { position: static; + height: auto; max-height: none; border-right: none; border-bottom: 1px solid var(--border-color); margin-bottom: 1rem; + flex: none; + min-width: 0; } - .site-header { - .site-title { - font-size: 1.25rem; - } - - .site-nav { - .page-link { - margin: 0 0.25rem; - font-size: 0.9rem; - } - } + .docs-content { + max-width: 100%; + padding: 1rem; } - - .page-content { - h1 { - font-size: 2rem; - } - - h2 { - font-size: 1.75rem; - } - - h3 { - font-size: 1.25rem; - } + + .path-cards { grid-template-columns: 1fr; } + + .site-header { + .site-title { font-size: 1.15rem; } + .site-nav .page-link { margin: 0 0.25rem; font-size: 0.85rem; } } - - .site-footer { - .footer-col-wrapper { - flex-direction: column; - gap: 1rem; - } + + .docs-content { + h1 { font-size: 1.75rem; } + h2 { font-size: 1.5rem; } + h3 { font-size: 1.15rem; } } + + .site-footer .footer-col-wrapper { flex-direction: column; gap: 1rem; } } -// Mermaid diagram styling +// ============================================================================ +// Mermaid diagrams +// ============================================================================ .mermaid { background-color: var(--bg-light) !important; padding: 1.5rem; @@ -523,56 +950,42 @@ body { border: 1px solid var(--border-color); margin: 1.5rem 0; overflow-x: auto; - - svg { - background-color: transparent !important; - } - - // Ensure text is visible - text { - fill: var(--text-color) !important; - } - - // Node styling - .node rect, - .node circle, - .node ellipse, - .node polygon { + transition: background-color 0.2s; + + svg { background-color: transparent !important; } + text { fill: var(--text-color) !important; } + + .node rect, .node circle, .node ellipse, .node polygon { fill: var(--bg-alt) !important; stroke: var(--primary-color) !important; } - - // Edge/arrow styling - .edgePath path, - .flowchart-link { - stroke: var(--primary-color) !important; - } - - .arrowheadPath { - fill: var(--primary-color) !important; - } - - // Label styling + + .edgePath path, .flowchart-link { stroke: var(--primary-color) !important; } + .arrowheadPath { fill: var(--primary-color) !important; } + .edgeLabel { background-color: var(--bg-light) !important; color: var(--text-color) !important; } - - .edgeLabel text { - fill: var(--text-color) !important; - } + .edgeLabel text { fill: var(--text-color) !important; } } -// Print styles +// ============================================================================ +// Print +// ============================================================================ @media print { - .site-header, - .site-footer { - display: none; - } - - .page-content { - max-width: 100%; - padding: 0; - } + .site-header, .site-footer, .docs-sidebar { display: none; } + .page-content { max-width: 100%; padding: 0; } + .docs-layout { display: block; } } +// ============================================================================ +// Sidebar filtering (expertise) +// ============================================================================ +.docs-nav li[data-expertise].hidden-by-filter { + display: none; +} + +.docs-nav-bundle.hidden-by-filter { + display: none; +} diff --git a/docs/authoring/adapter-development.md b/docs/authoring/adapter-development.md index b5ca7c5..c7f740c 100644 --- a/docs/authoring/adapter-development.md +++ b/docs/authoring/adapter-development.md @@ -5,6 +5,9 @@ permalink: /authoring/adapter-development/ redirect_from: - /guides/adapter-development/ description: Implement BridgeAdapter integrations for external tools. +keywords: [adapter, development, bridge, integration, authoring] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Adapter Development Guide diff --git a/docs/authoring/creating-custom-bridges.md b/docs/authoring/creating-custom-bridges.md index fa5b14d..3334a6e 100644 --- a/docs/authoring/creating-custom-bridges.md +++ b/docs/authoring/creating-custom-bridges.md @@ -4,6 +4,9 @@ title: Creating Custom Bridges permalink: /authoring/creating-custom-bridges/ redirect_from: - /guides/creating-custom-bridges/ +keywords: [bridge, custom, authoring, integration, extensibility] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Creating Custom Bridges diff --git a/docs/authoring/custom-registries.md b/docs/authoring/custom-registries.md index 47246f6..59be416 100644 --- a/docs/authoring/custom-registries.md +++ b/docs/authoring/custom-registries.md @@ -5,6 +5,9 @@ permalink: /authoring/custom-registries/ redirect_from: - /guides/custom-registries/ description: Add, list, and manage custom module registries with trust levels and priority. +keywords: [registry, custom, trust, priority, modules] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Custom registries diff --git a/docs/authoring/extending-projectbundle.md b/docs/authoring/extending-projectbundle.md index 2d5b866..08b6138 100644 --- a/docs/authoring/extending-projectbundle.md +++ b/docs/authoring/extending-projectbundle.md @@ -5,6 +5,9 @@ permalink: /authoring/extending-projectbundle/ redirect_from: - /guides/extending-projectbundle/ description: Add namespaced custom fields to Feature and ProjectBundle without modifying core models. +keywords: [projectbundle, extension, custom-fields, namespace, schema] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Extending ProjectBundle diff --git a/docs/authoring/module-development.md b/docs/authoring/module-development.md index 379f520..ef5bfbe 100644 --- a/docs/authoring/module-development.md +++ b/docs/authoring/module-development.md @@ -5,6 +5,9 @@ permalink: /authoring/module-development/ redirect_from: - /guides/module-development/ description: How to build and package SpecFact CLI modules. +keywords: [module, development, authoring, packaging, bundle] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Module Development Guide @@ -73,5 +76,5 @@ Extension/security fields: ## Related docs - [Architecture Reference](/architecture/) -- [Module System Architecture](../architecture/module-system.md) +- [Module Categories](/reference/module-categories/) - Module types and categories - [Adapter Development Guide](adapter-development.md) diff --git a/docs/authoring/module-signing.md b/docs/authoring/module-signing.md index c21f863..eeeaa27 100644 --- a/docs/authoring/module-signing.md +++ b/docs/authoring/module-signing.md @@ -5,6 +5,9 @@ permalink: /authoring/module-signing/ redirect_from: - /guides/module-signing-and-key-rotation/ description: Runbook for signing bundled modules, placing public keys, rotating keys, and revoking compromised keys. +keywords: [signing, security, verification, trust, modules] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Module Signing and Key Rotation diff --git a/docs/authoring/publishing-modules.md b/docs/authoring/publishing-modules.md index f3aa0cb..8499ebd 100644 --- a/docs/authoring/publishing-modules.md +++ b/docs/authoring/publishing-modules.md @@ -5,6 +5,9 @@ permalink: /authoring/publishing-modules/ redirect_from: - /guides/publishing-modules/ description: Package and publish SpecFact modules to a registry (tarball, checksum, optional signing). +keywords: [publishing, registry, tarball, checksum, modules] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Publishing modules diff --git a/docs/bundles/backlog/delta.md b/docs/bundles/backlog/delta.md index b98f26e..0ff5331 100644 --- a/docs/bundles/backlog/delta.md +++ b/docs/bundles/backlog/delta.md @@ -4,6 +4,9 @@ title: Backlog Delta Commands permalink: /bundles/backlog/delta/ redirect_from: - /guides/backlog-delta-commands/ +keywords: [backlog, delta, commands, diff, changes] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Backlog Delta Commands diff --git a/docs/bundles/backlog/dependency-analysis.md b/docs/bundles/backlog/dependency-analysis.md index 8ab417e..98e5cd4 100644 --- a/docs/bundles/backlog/dependency-analysis.md +++ b/docs/bundles/backlog/dependency-analysis.md @@ -4,6 +4,9 @@ title: Backlog Dependency Analysis permalink: /bundles/backlog/dependency-analysis/ redirect_from: - /guides/backlog-dependency-analysis/ +keywords: [backlog, dependency, analysis, graph, prioritization] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Backlog Dependency Analysis diff --git a/docs/bundles/backlog/overview.md b/docs/bundles/backlog/overview.md index 7b252c9..ba442c7 100644 --- a/docs/bundles/backlog/overview.md +++ b/docs/bundles/backlog/overview.md @@ -3,6 +3,9 @@ layout: default title: Backlog bundle overview nav_order: 2 permalink: /bundles/backlog/overview/ +keywords: [backlog, bundle, overview, refinement, stories] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- # Backlog bundle overview diff --git a/docs/bundles/backlog/policy-engine.md b/docs/bundles/backlog/policy-engine.md index f573b40..4e7ad4b 100644 --- a/docs/bundles/backlog/policy-engine.md +++ b/docs/bundles/backlog/policy-engine.md @@ -4,6 +4,9 @@ title: Policy Engine Commands permalink: /bundles/backlog/policy-engine/ redirect_from: - /guides/policy-engine-commands/ +keywords: [policy, engine, backlog, rules, enforcement] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Policy Engine Commands diff --git a/docs/bundles/backlog/refinement.md b/docs/bundles/backlog/refinement.md index 10593d7..4c68b82 100644 --- a/docs/bundles/backlog/refinement.md +++ b/docs/bundles/backlog/refinement.md @@ -4,6 +4,9 @@ title: Backlog Refinement Guide permalink: /bundles/backlog/refinement/ redirect_from: - /guides/backlog-refinement/ +keywords: [backlog, refinement, ceremony, sprint, agile] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Backlog Refinement Guide diff --git a/docs/bundles/code-review/ledger.md b/docs/bundles/code-review/ledger.md index 15f0911..d02af97 100644 --- a/docs/bundles/code-review/ledger.md +++ b/docs/bundles/code-review/ledger.md @@ -5,6 +5,9 @@ nav_order: 4 permalink: /bundles/code-review/ledger/ redirect_from: - /guides/code-review-ledger/ +keywords: [code-review, ledger, history, tracking, audit] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Code review ledger diff --git a/docs/bundles/code-review/overview.md b/docs/bundles/code-review/overview.md index 14654ea..fa33ad9 100644 --- a/docs/bundles/code-review/overview.md +++ b/docs/bundles/code-review/overview.md @@ -3,6 +3,9 @@ layout: default title: Code Review bundle overview nav_order: 2 permalink: /bundles/code-review/overview/ +keywords: [code-review, bundle, overview, review, quality] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- # Code Review bundle overview diff --git a/docs/bundles/code-review/rules.md b/docs/bundles/code-review/rules.md index 8a6bf93..1e788d8 100644 --- a/docs/bundles/code-review/rules.md +++ b/docs/bundles/code-review/rules.md @@ -5,6 +5,9 @@ nav_order: 5 permalink: /bundles/code-review/rules/ redirect_from: - /guides/code-review-rules/ +keywords: [code-review, rules, configuration, linting, quality] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Code review rules diff --git a/docs/bundles/code-review/run.md b/docs/bundles/code-review/run.md index 75eadf0..d99f3b1 100644 --- a/docs/bundles/code-review/run.md +++ b/docs/bundles/code-review/run.md @@ -5,6 +5,9 @@ nav_order: 3 permalink: /bundles/code-review/run/ redirect_from: - /guides/code-review-run/ +keywords: [code-review, run, execution, analysis, review] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Code review run diff --git a/docs/bundles/codebase/analyze.md b/docs/bundles/codebase/analyze.md index a23f60a..fc3454c 100644 --- a/docs/bundles/codebase/analyze.md +++ b/docs/bundles/codebase/analyze.md @@ -5,6 +5,9 @@ nav_order: 3 permalink: /bundles/codebase/analyze/ redirect_from: - /guides/code-analyze-contracts/ +keywords: [codebase, analyze, contracts, validation, code] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Code analyze contracts diff --git a/docs/bundles/codebase/drift.md b/docs/bundles/codebase/drift.md index 93f3a47..45063bb 100644 --- a/docs/bundles/codebase/drift.md +++ b/docs/bundles/codebase/drift.md @@ -5,6 +5,9 @@ nav_order: 4 permalink: /bundles/codebase/drift/ redirect_from: - /guides/code-drift-detect/ +keywords: [drift, detect, codebase, spec-sync, validation] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Code drift detect diff --git a/docs/bundles/codebase/overview.md b/docs/bundles/codebase/overview.md index e709b2e..5467686 100644 --- a/docs/bundles/codebase/overview.md +++ b/docs/bundles/codebase/overview.md @@ -3,6 +3,9 @@ layout: default title: Codebase bundle overview nav_order: 2 permalink: /bundles/codebase/overview/ +keywords: [codebase, bundle, overview, analysis, validation] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- # Codebase bundle overview diff --git a/docs/bundles/codebase/repro.md b/docs/bundles/codebase/repro.md index b629fdc..2c6d647 100644 --- a/docs/bundles/codebase/repro.md +++ b/docs/bundles/codebase/repro.md @@ -5,6 +5,9 @@ nav_order: 5 permalink: /bundles/codebase/repro/ redirect_from: - /guides/code-repro/ +keywords: [repro, codebase, reproduction, debugging, validation] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Code repro diff --git a/docs/bundles/codebase/sidecar-validation.md b/docs/bundles/codebase/sidecar-validation.md index 71c42e7..7599e1e 100644 --- a/docs/bundles/codebase/sidecar-validation.md +++ b/docs/bundles/codebase/sidecar-validation.md @@ -4,6 +4,9 @@ title: Sidecar Validation Guide permalink: /bundles/codebase/sidecar-validation/ redirect_from: - /guides/sidecar-validation/ +keywords: [sidecar, validation, codebase, contract, schema] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Sidecar Validation Guide diff --git a/docs/bundles/govern/enforce.md b/docs/bundles/govern/enforce.md index c327d30..9133011 100644 --- a/docs/bundles/govern/enforce.md +++ b/docs/bundles/govern/enforce.md @@ -5,6 +5,9 @@ nav_order: 3 permalink: /bundles/govern/enforce/ redirect_from: - /guides/govern-enforce/ +keywords: [govern, enforce, policy, compliance, rules] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Govern enforce diff --git a/docs/bundles/govern/overview.md b/docs/bundles/govern/overview.md index 3f3325f..b1b53df 100644 --- a/docs/bundles/govern/overview.md +++ b/docs/bundles/govern/overview.md @@ -3,6 +3,9 @@ layout: default title: Govern bundle overview nav_order: 2 permalink: /bundles/govern/overview/ +keywords: [govern, bundle, overview, policy, compliance] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- # Govern bundle overview diff --git a/docs/bundles/govern/patch.md b/docs/bundles/govern/patch.md index cb8cc7a..97f7697 100644 --- a/docs/bundles/govern/patch.md +++ b/docs/bundles/govern/patch.md @@ -5,6 +5,9 @@ nav_order: 4 permalink: /bundles/govern/patch/ redirect_from: - /guides/govern-patch/ +keywords: [govern, patch, apply, remediation, fix] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Govern patch apply diff --git a/docs/bundles/project/devops-flow.md b/docs/bundles/project/devops-flow.md index 352b287..ebfcaf8 100644 --- a/docs/bundles/project/devops-flow.md +++ b/docs/bundles/project/devops-flow.md @@ -4,6 +4,9 @@ title: Project DevOps Flow permalink: /bundles/project/devops-flow/ redirect_from: - /guides/project-devops-flow/ +keywords: [project, devops, flow, pipeline, automation] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Project DevOps Flow diff --git a/docs/bundles/project/import-migration.md b/docs/bundles/project/import-migration.md index 8b84577..87e99fd 100644 --- a/docs/bundles/project/import-migration.md +++ b/docs/bundles/project/import-migration.md @@ -4,6 +4,9 @@ title: Import Command Features permalink: /bundles/project/import-migration/ redirect_from: - /guides/import-features/ +keywords: [import, migration, project, onboarding, legacy] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Import Command Features @@ -239,9 +242,8 @@ If import is interrupted: ## Related Documentation - [Command Reference](/reference/commands/#import-from-code) - Complete command documentation -- [Quick Examples](../examples/quick-examples.md) - Quick command examples -- [Brownfield Engineer Guide](/brownfield-engineer/) - Complete brownfield workflow -- [Common Tasks](/common-tasks/) - Common import scenarios +- [Brownfield Modernization](/guides/brownfield-modernization/) - Complete brownfield workflow +- [First Steps](/getting-started/first-steps/) - Common command examples --- diff --git a/docs/bundles/project/overview.md b/docs/bundles/project/overview.md index d02b226..4cab884 100644 --- a/docs/bundles/project/overview.md +++ b/docs/bundles/project/overview.md @@ -3,6 +3,9 @@ layout: default title: Project bundle overview nav_order: 2 permalink: /bundles/project/overview/ +keywords: [project, bundle, overview, management, configuration] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- # Project bundle overview diff --git a/docs/bundles/spec/generate-tests.md b/docs/bundles/spec/generate-tests.md index bb52520..c4f443c 100644 --- a/docs/bundles/spec/generate-tests.md +++ b/docs/bundles/spec/generate-tests.md @@ -5,6 +5,9 @@ nav_order: 4 permalink: /bundles/spec/generate-tests/ redirect_from: - /guides/spec-generate-tests/ +keywords: [spec, generate-tests, testing, contract, automation] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Spec generate-tests diff --git a/docs/bundles/spec/mock.md b/docs/bundles/spec/mock.md index 4ed8531..59c34af 100644 --- a/docs/bundles/spec/mock.md +++ b/docs/bundles/spec/mock.md @@ -5,6 +5,9 @@ nav_order: 5 permalink: /bundles/spec/mock/ redirect_from: - /guides/spec-mock/ +keywords: [spec, mock, testing, stub, simulation] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Spec mock diff --git a/docs/bundles/spec/overview.md b/docs/bundles/spec/overview.md index 5138461..2e7f220 100644 --- a/docs/bundles/spec/overview.md +++ b/docs/bundles/spec/overview.md @@ -3,6 +3,9 @@ layout: default title: Spec bundle overview nav_order: 2 permalink: /bundles/spec/overview/ +keywords: [spec, bundle, overview, validation, openapi] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- # Spec bundle overview diff --git a/docs/bundles/spec/validate.md b/docs/bundles/spec/validate.md index edeaed2..1210448 100644 --- a/docs/bundles/spec/validate.md +++ b/docs/bundles/spec/validate.md @@ -6,6 +6,9 @@ permalink: /bundles/spec/validate/ redirect_from: - /guides/spec-validate/ - /guides/spec-backward-compat/ +keywords: [spec, validate, backward-compatibility, breaking-changes, openapi] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # Spec validate and backward compatibility diff --git a/docs/getting-started/choose-your-modules.md b/docs/getting-started/choose-your-modules.md new file mode 100644 index 0000000..afe8358 --- /dev/null +++ b/docs/getting-started/choose-your-modules.md @@ -0,0 +1,314 @@ +--- +title: Choose Your Modules +layout: default +permalink: /getting-started/choose-your-modules/ +keywords: [modules, bundles, comparison, use cases, which module, getting started, install, USP] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] +--- + +# Choose Your Modules + +SpecFact ships as six independent modules. Each solves a distinct problem in your development workflow. You install only what you need. + +> **CLI vs AI IDE:** SpecFact CLI is fully deterministic — no AI built in. All commands produce structured, reproducible output. For AI-assisted workflows, each module ships **IDE slash prompts** that you install with `specfact init ide`. These prompts feed CLI output to your IDE's AI (Cursor, Claude Code, VS Code/Copilot, Windsurf, and [10+ more]({{ '/ai-ide-workflow/' | relative_url }})) for interactive analysis and refinement. + +## Quick Decision Guide + +**"I need to..."** — find your starting point: + +| I need to... | Install this | Command surface | +|---|---|---| +| Manage my backlog with template-driven refinement, standups, and sprint planning | **Backlog** | `specfact backlog` | +| Structure my project, link plans to code, and manage dev lifecycle | **Project** | `specfact project`, `specfact plan`, `specfact sync` | +| Import a legacy codebase, detect features, and track spec drift | **Codebase** | `specfact code import`, `specfact code drift` | +| Run governed code reviews with quality scoring and house rules | **Code Review** | `specfact code review` | +| Validate OpenAPI/AsyncAPI contracts and generate test suites | **Spec** | `specfact spec validate`, `specfact spec mock` | +| Enforce quality gates before merge or release | **Govern** | `specfact govern enforce` | + +## Module Overview + +### Backlog — Template-Driven Backlog Management + +**The problem it solves:** Your team wastes hours in refinement meetings, stories lack acceptance criteria, and nobody tracks what changed between sprints. + +**What it does:** +- Connects to GitHub Issues or Azure DevOps and syncs your backlog items +- Runs deterministic refinement: detects story type (user story, defect, spike, enabler), scores completeness confidence, validates Definition of Ready +- Automates ceremonies: daily standup summaries, refinement checklists, planning assistance, kanban flow tracking +- Tracks deltas between sprint snapshots: what moved, what's at risk, estimated cost of changes +- Enforces backlog policies per framework (Scrum, Kanban, SAFe) +- Ships IDE slash prompts (via `specfact init ide`) that feed CLI output to your AI IDE for interactive refinement + +**Best for:** Any team managing a backlog — from solo developers tracking GitHub issues to enterprise teams running SAFe on Azure DevOps. + +```bash +specfact module install nold-ai/specfact-backlog +specfact backlog --help +``` + +[Full Backlog docs →]({{ '/bundles/backlog/overview/' | relative_url }}) + +--- + +### Project — Project Structure and Lifecycle + +**The problem it solves:** Your plans live in documents, your code lives in repos, and nothing connects the two. Feature work has no traceable path from idea to release. + +**What it does:** +- Creates structured project bundles that link plans to code +- Manages development plans with feature/story tracking aligned to Software Design Documents (SDDs) +- Syncs with external tools: OpenSpec, Spec-Kit, GitHub, Linear, Jira +- Provides a DevOps flow with explicit stages: plan → develop → review → release → monitor +- Imports brownfield codebases with automatic feature detection + +**Best for:** Teams that want traceable connections between planning artifacts and code, or anyone modernizing a legacy codebase. + +```bash +specfact module install nold-ai/specfact-project +specfact project --help +``` + +[Full Project docs →]({{ '/bundles/project/overview/' | relative_url }}) + +--- + +### Codebase — Code Analysis and Drift Detection + +**The problem it solves:** Your implementation drifted from the spec months ago, you have orphaned API endpoints nobody documented, and your test coverage doesn't match your contracts. + +**What it does:** +- Imports existing codebases and detects features using AST parsing and semantic analysis +- Measures OpenAPI contract coverage: which endpoints have specs, which don't +- Detects drift between specs and implementation — finds orphaned specs, missing tests, and alignment gaps +- Validates external codebases via sidecar mode (no source modification) +- Runs reproducibility suites: lint, type-check, contract validation, and CrossHair property tests + +**Best for:** Teams with existing codebases that need to understand what they have, where specs are missing, and what drifted. + +**Requires:** Project module (installed automatically as dependency). + +```bash +specfact module install nold-ai/specfact-codebase +specfact code analyze --help +specfact code drift --help +``` + +[Full Codebase docs →]({{ '/bundles/codebase/overview/' | relative_url }}) + +--- + +### Code Review — Governed Quality Reviews + +**The problem it solves:** Code reviews are inconsistent, quality is subjective, and there's no measurable record of improvement over time. + +**What it does:** +- Runs governed code reviews with deterministic quality scoring (not just linting — structural analysis) +- Bundles Ruff, Semgrep, Pylint, Pytest, Radon, BasedPyright, and CrossHair for comprehensive analysis +- Maintains a review ledger: tracks coins/streaks, violations over time, and team statistics +- Supports house rules per IDE (Cursor, Claude Code, Codex, Windsurf) to enforce consistent quality standards +- Validates TDD gates: did tests come before implementation? + +**Best for:** Any developer or team that wants measurable, consistent code quality. Works standalone — no other modules required. + +```bash +specfact module install nold-ai/specfact-code-review +specfact code review run --help +``` + +[Full Code Review docs →]({{ '/bundles/code-review/overview/' | relative_url }}) + +--- + +### Spec — Contract Validation and Test Generation + +**The problem it solves:** Your OpenAPI specs exist but nobody validates them against the actual code, breaking changes slip through, and writing contract tests is tedious. + +**What it does:** +- Validates OpenAPI and AsyncAPI contracts using Specmatic with example verification +- Detects backward-incompatible changes between spec versions before they reach production +- Generates test suites directly from your contracts — no manual test writing +- Spins up mock servers from specs for frontend development and integration testing +- Bootstraps and validates Software Design Document (SDD) constitutions + +**Best for:** Teams with API contracts that need validation, backward compatibility checks, and generated test suites. + +**Requires:** Project module (installed automatically as dependency). + +```bash +specfact module install nold-ai/specfact-spec +specfact spec validate --help +specfact spec mock --help +``` + +[Full Spec docs →]({{ '/bundles/spec/overview/' | relative_url }}) + +--- + +### Govern — Quality Gates and Enforcement + +**The problem it solves:** Quality standards exist on paper but nothing enforces them before merge or release. Patches are applied manually and inconsistently. + +**What it does:** +- Enforces quality gates at configurable strictness levels: minimal, balanced, or strict +- Validates SDD compliance: checks bundle state, thresholds, and frozen sections before promotion +- Manages patches with explicit preview → apply → verify flow and write authorization gates +- Works in both interactive mode and CI/CD pipelines + +**Best for:** Teams that need automated quality enforcement before merges and releases, especially in CI/CD pipelines. + +**Requires:** Project module (installed automatically as dependency). + +```bash +specfact module install nold-ai/specfact-govern +specfact govern enforce --help +``` + +[Full Govern docs →]({{ '/bundles/govern/overview/' | relative_url }}) + +--- + +## Side-by-Side Comparison + +| | Backlog | Project | Codebase | Code Review | Spec | Govern | +|---|---|---|---|---|---|---| +| **One-line USP** | Template-driven backlog refinement & ceremonies | Plan-to-code traceability | Legacy import & drift detection | Governed quality scoring | Contract validation & test gen | Quality gate enforcement | +| **Dependencies** | None | None | Project | None | Project | Project | +| **Works standalone** | Yes | Yes | No | Yes | No | No | +| **Connects to external tools** | GitHub, Azure DevOps | GitHub, Linear, Jira, OpenSpec | — | — | Specmatic | — | +| **CI/CD ready** | Yes | Yes | Yes | Yes (score-only mode) | Yes | Yes (non-interactive) | +| **Solo developer** | Great | Great | Great | Great | Useful | Optional | +| **Team use** | Essential | Essential | Very useful | Essential | Very useful | Very useful | +| **Enterprise** | Essential | Essential | Essential | Essential | Essential | Essential | + +## Recommended Install Profiles + +### Solo Developer — Start simple + +```bash +specfact init --profile solo-developer +# Installs: backlog + code-review +``` + +You get template-driven backlog management for your GitHub issues and governed code reviews. Install IDE slash prompts with `specfact init ide` for AI-assisted workflows. Add more modules as your project grows. + +### Small Team — Full workflow + +```bash +specfact init --install backlog,project,code-review,spec +``` + +Covers backlog management, plan-to-code traceability, code reviews, and contract validation. Your team gets shared quality standards through house rules. + +### Enterprise — Everything + +```bash +specfact init --install all +``` + +All six modules. Adds governance enforcement, codebase drift detection, and the full compliance pipeline. Pair with [Enterprise Configuration]({{ '/team-and-enterprise/enterprise-config/' | relative_url }}) for multi-repo setups. + +## How Modules Work Together + +```mermaid +graph TD + BL["Backlog
Refinement & ceremonies"] + CR["Code Review
Quality scoring & rules"] + PR["Project
Plan-to-code traceability"] + CB["Codebase
Import & drift detection"] + SP["Spec
Contract validation & tests"] + GV["Govern
Quality gate enforcement"] + + BL -- "sync work items" --> PR + CR -- "review changes" --> PR + PR -- "analyze code" --> CB + PR -- "validate contracts" --> SP + PR -- "enforce gates" --> GV +``` + +**Backlog** feeds work items into **Project** plans. **Project** connects plans to code that **Codebase** analyzes for drift. **Spec** validates the contracts that **Project** references. **Code Review** scores quality on every change. **Govern** enforces gates before merge and release. + +--- + +## Customization Options by Module + +For intermediate and advanced users — each module provides configuration hooks to adapt behavior to your team's workflow. + +### Backlog Customizations + +| What | How | Use case | +|---|---|---| +| **Field mapping** | `specfact backlog map-fields` or `.specfact/backlog-config.yaml` | Azure DevOps custom process templates with non-standard fields | +| **Adapter selection** | `.specfact/backlog-config.yaml` | Switch between GitHub Issues and Azure DevOps | +| **Policy framework** | `.specfact/policy.yaml` | Choose Scrum, Kanban, SAFe, or mixed framework rules | +| **Refinement templates** | Provider + framework + persona resolution | Custom refinement templates per story type (used by CLI and IDE slash prompts) | +| **Ceremony config** | `.specfact/standup.yaml` | Customize standup format, sprint boundaries, and output | + +[Backlog deep dives →]({{ '/bundles/backlog/overview/' | relative_url }}) · [Custom Field Mapping guide →]({{ '/guides/custom-field-mapping/' | relative_url }}) + +### Project Customizations + +| What | How | Use case | +|---|---|---| +| **Sync bridges** | `specfact sync bridge` config | Connect to GitHub, Linear, Jira, OpenSpec, Spec-Kit | +| **Personas** | `specfact project init-personas` | Map team roles to project bundle access | +| **Import entry points** | `specfact code import --entry-point` | Specify monorepo roots for brownfield analysis | +| **DevOps stages** | Stage action configuration | Customize the plan → develop → review → release flow | + +[Project deep dives →]({{ '/bundles/project/overview/' | relative_url }}) + +### Codebase Customizations + +| What | How | Use case | +|---|---|---| +| **Framework extractors** | Auto-detected (Django, FastAPI, Flask, DRF) | Framework-specific feature detection during import | +| **Confidence thresholds** | CLI flags | Tune sensitivity of feature detection | +| **CrossHair depth** | `--crosshair-timeout` | Control property test exploration time | +| **Sidecar workspace** | `specfact code validate sidecar init` | Validate external repos without modifying source | + +[Codebase deep dives →]({{ '/bundles/codebase/overview/' | relative_url }}) + +### Code Review Customizations + +| What | How | Use case | +|---|---|---| +| **House rules** | `specfact code review rules init` | Per-IDE quality rules (Cursor, Claude Code, Codex, Windsurf) | +| **Review scope** | `--scope changed` vs `--scope full` | Review only changed files or entire codebase | +| **Test inclusion** | `--include-tests` / `--exclude-tests` | Control whether test files are reviewed | +| **Score-only mode** | `--score-only` | CI/CD integration — just the score, no details | +| **Ledger management** | `specfact code review ledger` | Track quality trends, streaks, and team stats | + +[Code Review deep dives →]({{ '/bundles/code-review/overview/' | relative_url }}) + +### Spec Customizations + +| What | How | Use case | +|---|---|---| +| **Validation caching** | `--force-refresh` | Control when cached validation results expire | +| **Mock server port** | `--port` | Run multiple mock servers in parallel | +| **Test output directory** | `--output-dir` | Custom location for generated test suites | +| **SDD constitution** | `specfact spec sdd constitution` | Customize Software Design Document templates | +| **Generation prompts** | IDE persona configuration | Customize AI-generated contract prompts per IDE | + +[Spec deep dives →]({{ '/bundles/spec/overview/' | relative_url }}) + +### Govern Customizations + +| What | How | Use case | +|---|---|---| +| **Enforcement presets** | `--preset minimal/balanced/strict` | Choose strictness level for quality gates | +| **SDD manifest path** | `--sdd-manifest` | Point to custom SDD location | +| **Output format** | `--format yaml/json/markdown` | Choose report format for CI/CD integration | +| **Non-interactive mode** | `--yes` | Automated pipelines — skip all prompts | +| **Dry-run patches** | `--dry-run` | Preview patch effects before applying | + +[Govern deep dives →]({{ '/bundles/govern/overview/' | relative_url }}) + +--- + +## Next Steps + +- [Installation]({{ '/getting-started/installation/' | relative_url }}) — Install SpecFact CLI and your chosen modules +- [First Steps]({{ '/getting-started/first-steps/' | relative_url }}) — Run your first commands +- [Module Bootstrap Checklist]({{ '/getting-started/module-bootstrap-checklist/' | relative_url }}) — Verify your setup +- [Cross-Module Chains]({{ '/guides/cross-module-chains/' | relative_url }}) — See how modules work together in real workflows diff --git a/docs/getting-started/first-steps.md b/docs/getting-started/first-steps.md index b053ddf..70cb7a8 100644 --- a/docs/getting-started/first-steps.md +++ b/docs/getting-started/first-steps.md @@ -2,31 +2,174 @@ layout: default title: Your First Steps with SpecFact CLI permalink: /getting-started/first-steps/ +keywords: [getting-started, first-steps, quickstart, tutorial, beginner, install, first command] +audience: [solo, team, enterprise] +expertise_level: [beginner] --- -# Legacy Workflow Note +# Your First Steps with SpecFact CLI -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. +This guide walks you through your first commands after installing SpecFact CLI. If you haven't installed yet, start with the [Installation guide]({{ '/getting-started/installation/' | relative_url }}). -Use the current mounted entrypoints instead: +Not sure which modules to install? See [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}). -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` +## 1. Verify Your Installation -When you need exact syntax, verify against live help in the current release, for example: +```bash +specfact --version +specfact --help +``` + +You should see the CLI version and the top-level command groups. The available commands depend on which modules you have installed. + +## 2. Install Your First Modules + +Pick a profile or install modules individually: + +```bash +# Option A: Use a profile (installs a curated set) +specfact init --profile solo-developer + +# Option B: Install specific modules +specfact module install nold-ai/specfact-backlog +specfact module install nold-ai/specfact-code-review +``` + +Verify what's installed: + +```bash +specfact module list +``` + +## 3. Explore the Command Surface + +Each module mounts its commands under a top-level group. After installing, explore what's available: + +```bash +# Backlog management +specfact backlog --help + +# Code review +specfact code review --help + +# Project management (if installed) +specfact project --help + +# Spec validation (if installed) +specfact spec --help + +# Governance enforcement (if installed) +specfact govern --help +``` + +## 4. Run Your First Code Review + +The simplest way to see SpecFact in action — run a governed code review on your current project: + +```bash +cd your-project/ +specfact code review run +``` + +This analyzes your code with Ruff, Semgrep, Pylint, BasedPyright, Radon, and CrossHair, then produces a quality score. No configuration needed. + +To review only changed files: ```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help +specfact code review run --scope changed ``` -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +Check your quality ledger over time: + +```bash +specfact code review ledger status +``` + +## 5. Connect Your Backlog + +If you installed the Backlog module, connect it to your issue tracker: + +**GitHub Issues:** + +```bash +specfact backlog auth github +specfact backlog daily +``` + +**Azure DevOps:** + +```bash +specfact backlog auth azure-devops +specfact backlog daily +``` + +The `daily` command generates a standup summary from your backlog — what moved, what's blocked, what needs attention. + +## 6. Run Backlog Refinement + +The CLI provides deterministic template detection and validation: + +```bash +specfact backlog refine +``` + +This detects the story type (user story, defect, spike, enabler), scores completeness confidence, and checks Definition of Ready criteria. The output is structured data — no AI is involved at this step. + +**Want AI-powered refinement?** Install IDE slash prompts (see step 7), then use the `/specfact.backlog-refine` slash command in your IDE. The AI reads the CLI output and interactively helps you improve story quality, fix underspecification, and split oversized stories. + +## 7. Install IDE Slash Prompts (Optional) + +SpecFact CLI itself is fully deterministic — no AI built in. AI-assisted workflows are delivered via **slash prompts** that you install into your IDE. The prompts call CLI commands under the hood and let your IDE's AI interpret and act on the results. + +```bash +# Auto-detects your IDE and installs all available slash prompts +specfact init ide + +# Or specify your IDE explicitly +specfact init ide --ide cursor +specfact init ide --ide claude +specfact init ide --ide vscode +``` + +**Supported IDEs:** Cursor, Claude Code, VS Code / GitHub Copilot, Windsurf, Gemini CLI, Qwen Code, opencode, Kilo Code, Auggie, Roo Code, CodeBuddy, Amp, Amazon Q Developer. + +After installation, you get slash commands like: + +| Slash command | What it does | +|---|---| +| `/specfact.01-import` | Import codebase → extract routes, schemas, contracts; AI enriches context | +| `/specfact.02-plan` | Create and manage project plans with AI assistance | +| `/specfact.03-review` | Review plan quality, identify gaps, promote stages | +| `/specfact.backlog-refine` | Interactive AI refinement of backlog items | +| `/specfact.backlog-daily` | AI-enhanced daily standup from backlog data | +| `/specfact.07-contracts` | Analyze contract coverage, generate and apply contracts | +| `/specfact.validate` | Run validation suite with AI interpretation | + +Each prompt calls SpecFact CLI commands and feeds the structured output to your IDE's AI for interactive analysis. + +For detailed setup: [AI IDE Workflow Guide]({{ '/ai-ide-workflow/' | relative_url }}) + +## 8. Set Up House Rules (Optional) + +House rules enforce consistent quality standards in your AI IDE's code generation: + +```bash +# Initialize rules for your IDE +specfact code review rules init + +# View current rules +specfact code review rules show +``` + +These rules are checked during governed code reviews (`specfact code review run`) and are also available as context for AI IDEs after `specfact init ide`. + +## What's Next? + +Depending on your role and goals: + +- **Want deeper backlog workflows?** → [Backlog Quickstart Demo]({{ '/getting-started/tutorial-backlog-quickstart-demo/' | relative_url }}) +- **Need contract validation?** → [Spec Bundle Overview]({{ '/bundles/spec/overview/' | relative_url }}) +- **Working with legacy code?** → [Import & Migration]({{ '/bundles/project/import-migration/' | relative_url }}) +- **Setting up for a team?** → [Team Collaboration]({{ '/team-and-enterprise/team-collaboration/' | relative_url }}) +- **Want CI/CD integration?** → [CI/CD Pipeline Guide]({{ '/guides/ci-cd-pipeline/' | relative_url }}) +- **Full module comparison** → [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 5ba80f3..cd12e0b 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -2,6 +2,9 @@ layout: default title: Getting Started with SpecFact CLI permalink: /getting-started/installation/ +keywords: [install, setup, getting-started, pip, module] +audience: [solo, team, enterprise] +expertise_level: [beginner] --- # Getting Started with SpecFact CLI diff --git a/docs/getting-started/module-bootstrap-checklist.md b/docs/getting-started/module-bootstrap-checklist.md index c4f8fd8..acf7f7e 100644 --- a/docs/getting-started/module-bootstrap-checklist.md +++ b/docs/getting-started/module-bootstrap-checklist.md @@ -3,6 +3,9 @@ layout: default title: Module Bootstrap Checklist permalink: /getting-started/module-bootstrap-checklist/ description: Quick checklist to verify bundled modules are installed and discoverable in user/project scope. +keywords: [bootstrap, checklist, modules, setup, verification] +audience: [solo, team, enterprise] +expertise_level: [beginner] --- # Module Bootstrap Checklist diff --git a/docs/getting-started/tutorial-backlog-quickstart-demo.md b/docs/getting-started/tutorial-backlog-quickstart-demo.md index f305bb0..cf145ee 100644 --- a/docs/getting-started/tutorial-backlog-quickstart-demo.md +++ b/docs/getting-started/tutorial-backlog-quickstart-demo.md @@ -3,6 +3,9 @@ layout: default title: Tutorial - Backlog Quickstart Demo (GitHub + ADO) description: Short end-to-end demo for backlog init-config, map-fields, daily, and refine on GitHub and Azure DevOps. permalink: /getting-started/tutorial-backlog-quickstart-demo/ +keywords: [tutorial, backlog, quickstart, demo, github, azure-devops] +audience: [solo, team, enterprise] +expertise_level: [beginner] --- # Tutorial: Backlog Quickstart Demo (GitHub + ADO) diff --git a/docs/getting-started/tutorial-backlog-refine-ai-ide.md b/docs/getting-started/tutorial-backlog-refine-ai-ide.md index 167eaa2..3bb7431 100644 --- a/docs/getting-started/tutorial-backlog-refine-ai-ide.md +++ b/docs/getting-started/tutorial-backlog-refine-ai-ide.md @@ -3,6 +3,9 @@ layout: default title: Tutorial - Backlog Refine with Your AI IDE description: Integrate SpecFact CLI backlog refinement with your AI IDE. Improve story quality, underspec/overspec, split stories, fix ambiguities, respect DoR, and use custom template mapping. permalink: /getting-started/tutorial-backlog-refine-ai-ide/ +keywords: [tutorial, backlog, refinement, ai-ide, story-quality] +audience: [solo, team, enterprise] +expertise_level: [beginner] --- # Tutorial: Backlog Refine with Your AI IDE (Agile DevOps Teams) diff --git a/docs/getting-started/tutorial-daily-standup-sprint-review.md b/docs/getting-started/tutorial-daily-standup-sprint-review.md index 1ae1be8..7aad7ed 100644 --- a/docs/getting-started/tutorial-daily-standup-sprint-review.md +++ b/docs/getting-started/tutorial-daily-standup-sprint-review.md @@ -3,6 +3,9 @@ layout: default title: Tutorial - Daily Standup and Sprint Review with SpecFact CLI description: End-to-end daily standup and sprint review using specfact backlog ceremony standup. Auto-detect repo from git (GitHub or Azure DevOps), view standup table, post standup comments, use interactive mode and Copilot export. permalink: /getting-started/tutorial-daily-standup-sprint-review/ +keywords: [tutorial, standup, sprint-review, daily, ceremony] +audience: [solo, team, enterprise] +expertise_level: [beginner] --- # Tutorial: Daily Standup and Sprint Review with SpecFact CLI diff --git a/docs/getting-started/tutorial-openspec-speckit.md b/docs/getting-started/tutorial-openspec-speckit.md deleted file mode 100644 index 2ce11b0..0000000 --- a/docs/getting-started/tutorial-openspec-speckit.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: default -title: OpenSpec and Speckit Legacy Workflow Note -permalink: /getting-started/tutorial-openspec-speckit/ ---- - -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/agile-scrum-workflows.md b/docs/guides/agile-scrum-workflows.md index 61a18e3..9ddc88e 100644 --- a/docs/guides/agile-scrum-workflows.md +++ b/docs/guides/agile-scrum-workflows.md @@ -2,6 +2,9 @@ layout: default title: Agile/Scrum Workflows with SpecFact CLI permalink: /guides/agile-scrum-workflows/ +keywords: [agile, scrum, workflow, ceremony, sprint] +audience: [solo, team] +expertise_level: [intermediate] --- # Agile/Scrum Workflows with SpecFact CLI diff --git a/docs/guides/ai-ide-workflow.md b/docs/guides/ai-ide-workflow.md index 0ab4a94..d291a37 100644 --- a/docs/guides/ai-ide-workflow.md +++ b/docs/guides/ai-ide-workflow.md @@ -4,6 +4,9 @@ title: AI IDE Workflow Guide permalink: /ai-ide-workflow/ redirect_from: - /guides/ai-ide-workflow/ +keywords: [ai-ide, workflow, copilot, integration, prompt] +audience: [solo, team] +expertise_level: [intermediate] --- # AI IDE Workflow Guide diff --git a/docs/guides/brownfield-engineer.md b/docs/guides/brownfield-engineer.md index cb9a640..279d953 100644 --- a/docs/guides/brownfield-engineer.md +++ b/docs/guides/brownfield-engineer.md @@ -1,6 +1,5 @@ --- layout: default -title: Modernizing Legacy Code (Brownfield Engineer Guide) permalink: /brownfield-engineer/ redirect_from: - /guides/brownfield-engineer/ diff --git a/docs/guides/brownfield-examples.md b/docs/guides/brownfield-examples.md index 40bda86..99cebd3 100644 --- a/docs/guides/brownfield-examples.md +++ b/docs/guides/brownfield-examples.md @@ -2,6 +2,9 @@ layout: default title: Brownfield Examples permalink: /guides/brownfield-examples/ +keywords: [brownfield, examples, modernization, patterns, legacy] +audience: [solo, team] +expertise_level: [intermediate] --- # Brownfield Examples diff --git a/docs/guides/brownfield-faq-and-roi.md b/docs/guides/brownfield-faq-and-roi.md index 8e12616..f63ab63 100644 --- a/docs/guides/brownfield-faq-and-roi.md +++ b/docs/guides/brownfield-faq-and-roi.md @@ -2,6 +2,9 @@ layout: default title: Brownfield FAQ and ROI permalink: /guides/brownfield-faq-and-roi/ +keywords: [brownfield, faq, roi, planning, investment] +audience: [solo, team] +expertise_level: [intermediate] --- # Brownfield FAQ and ROI diff --git a/docs/guides/brownfield-faq.md b/docs/guides/brownfield-faq.md index 43029c4..03afca2 100644 --- a/docs/guides/brownfield-faq.md +++ b/docs/guides/brownfield-faq.md @@ -1,6 +1,5 @@ --- layout: default -title: Brownfield Modernization FAQ permalink: /brownfield-faq/ redirect_from: - /guides/brownfield-faq/ diff --git a/docs/guides/brownfield-journey.md b/docs/guides/brownfield-journey.md index aef4846..9802921 100644 --- a/docs/guides/brownfield-journey.md +++ b/docs/guides/brownfield-journey.md @@ -1,6 +1,5 @@ --- layout: default -title: Brownfield Modernization Journey permalink: /brownfield-journey/ redirect_from: - /guides/brownfield-journey/ diff --git a/docs/guides/brownfield-modernization.md b/docs/guides/brownfield-modernization.md index 46ffca1..4d837bf 100644 --- a/docs/guides/brownfield-modernization.md +++ b/docs/guides/brownfield-modernization.md @@ -2,6 +2,9 @@ layout: default title: Brownfield Modernization permalink: /guides/brownfield-modernization/ +keywords: [brownfield, modernization, legacy, migration, code] +audience: [solo, team] +expertise_level: [intermediate] --- # Brownfield Modernization diff --git a/docs/guides/brownfield-roi.md b/docs/guides/brownfield-roi.md index 8b1368c..5b6031d 100644 --- a/docs/guides/brownfield-roi.md +++ b/docs/guides/brownfield-roi.md @@ -1,6 +1,5 @@ --- layout: default -title: Brownfield Modernization ROI with SpecFact permalink: /brownfield-roi/ redirect_from: - /guides/brownfield-roi/ diff --git a/docs/guides/ci-cd-pipeline.md b/docs/guides/ci-cd-pipeline.md index 54144a5..da96c40 100644 --- a/docs/guides/ci-cd-pipeline.md +++ b/docs/guides/ci-cd-pipeline.md @@ -2,6 +2,9 @@ layout: default title: CI/CD Pipeline permalink: /guides/ci-cd-pipeline/ +keywords: [ci-cd, pipeline, automation, gates, quality] +audience: [solo, team] +expertise_level: [intermediate] --- # CI/CD Pipeline diff --git a/docs/guides/command-chains.md b/docs/guides/command-chains.md index e0319b5..6145477 100644 --- a/docs/guides/command-chains.md +++ b/docs/guides/command-chains.md @@ -2,6 +2,9 @@ layout: default title: Command Chains Reference permalink: /guides/command-chains/ +keywords: [command-chains, workflow, automation, sequences, cli] +audience: [solo, team] +expertise_level: [intermediate] --- # Command Chains Reference diff --git a/docs/guides/common-tasks.md b/docs/guides/common-tasks.md index c6d438f..005b37c 100644 --- a/docs/guides/common-tasks.md +++ b/docs/guides/common-tasks.md @@ -4,31 +4,9 @@ title: Common Tasks Quick Reference permalink: /common-tasks/ redirect_from: - /guides/common-tasks/ +keywords: [common-tasks, redirect, getting-started] +audience: [solo, team] +expertise_level: [beginner, intermediate] --- -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This page has been replaced. See [First Steps]({{ '/getting-started/first-steps/' | relative_url }}) for common task examples, or [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}) for a guide to all available commands. diff --git a/docs/guides/competitive-analysis.md b/docs/guides/competitive-analysis.md index eaf37b1..825218f 100644 --- a/docs/guides/competitive-analysis.md +++ b/docs/guides/competitive-analysis.md @@ -4,20 +4,9 @@ title: Competitive Analysis permalink: /competitive-analysis/ redirect_from: - /guides/competitive-analysis/ +keywords: [competitive, analysis, comparison, tools, evaluation] +audience: [solo, team] +expertise_level: [intermediate] --- -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. +This page has been replaced. For a comparison of SpecFact modules and their use cases, see [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}). diff --git a/docs/guides/contract-testing-workflow.md b/docs/guides/contract-testing-workflow.md index 0ba3b8d..cb19cf7 100644 --- a/docs/guides/contract-testing-workflow.md +++ b/docs/guides/contract-testing-workflow.md @@ -4,6 +4,9 @@ title: Contract Testing Workflow permalink: /contract-testing-workflow/ redirect_from: - /guides/contract-testing-workflow/ +keywords: [contract-testing, specmatic, validation, backward-compatibility, workflow] +audience: [solo, team] +expertise_level: [intermediate] --- # Contract Testing Workflow diff --git a/docs/guides/copilot-mode.md b/docs/guides/copilot-mode.md index 02c6b99..fb74fbb 100644 --- a/docs/guides/copilot-mode.md +++ b/docs/guides/copilot-mode.md @@ -4,20 +4,9 @@ title: Using CoPilot Mode permalink: /copilot-mode/ redirect_from: - /guides/copilot-mode/ +keywords: [copilot, mode, ai-assistant, interactive, workflow] +audience: [solo, team] +expertise_level: [intermediate] --- -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. +This page has been replaced. AI IDE integration is now handled through house rules in the Code Review module. See [Code Review Rules]({{ '/bundles/code-review/rules/' | relative_url }}) for per-IDE configuration. diff --git a/docs/guides/cross-module-chains.md b/docs/guides/cross-module-chains.md index cb065c1..e0c16a6 100644 --- a/docs/guides/cross-module-chains.md +++ b/docs/guides/cross-module-chains.md @@ -2,6 +2,9 @@ layout: default title: Cross-Module Chains permalink: /guides/cross-module-chains/ +keywords: [cross-module, chains, workflow, integration, pipeline] +audience: [solo, team] +expertise_level: [intermediate] --- # Cross-Module Chains diff --git a/docs/guides/custom-field-mapping.md b/docs/guides/custom-field-mapping.md index 30d3523..0be4880 100644 --- a/docs/guides/custom-field-mapping.md +++ b/docs/guides/custom-field-mapping.md @@ -2,6 +2,9 @@ layout: default title: Custom Field Mapping Guide permalink: /guides/custom-field-mapping/ +keywords: [custom-fields, mapping, adapter, configuration, devops] +audience: [solo, team] +expertise_level: [intermediate] --- # Custom Field Mapping Guide diff --git a/docs/guides/daily-devops-routine.md b/docs/guides/daily-devops-routine.md index d7cc3ce..02e02aa 100644 --- a/docs/guides/daily-devops-routine.md +++ b/docs/guides/daily-devops-routine.md @@ -2,6 +2,9 @@ layout: default title: Daily DevOps Routine permalink: /guides/daily-devops-routine/ +keywords: [daily, devops, routine, standup, workflow] +audience: [solo, team] +expertise_level: [intermediate] --- # Daily DevOps Routine diff --git a/docs/guides/dual-stack-enrichment.md b/docs/guides/dual-stack-enrichment.md index 05fbb1b..f6e7d17 100644 --- a/docs/guides/dual-stack-enrichment.md +++ b/docs/guides/dual-stack-enrichment.md @@ -4,31 +4,9 @@ title: Dual-Stack Enrichment permalink: /dual-stack-enrichment/ redirect_from: - /guides/dual-stack-enrichment/ +keywords: [dual-stack, enrichment, workflow, integration, data] +audience: [solo, team] +expertise_level: [intermediate] --- -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This page has been replaced. Enrichment workflows are now part of the Backlog and Project bundles. See [Backlog Refinement]({{ '/bundles/backlog/refinement/' | relative_url }}) or [Project DevOps Flow]({{ '/bundles/project/devops-flow/' | relative_url }}). diff --git a/docs/guides/ide-integration.md b/docs/guides/ide-integration.md index c22f34d..b4b0f8d 100644 --- a/docs/guides/ide-integration.md +++ b/docs/guides/ide-integration.md @@ -1,32 +1,7 @@ --- layout: default -title: IDE Integration with SpecFact CLI permalink: /guides/ide-integration/ +redirect_to: /ai-ide-workflow/ --- -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This guide moved to [AI IDE Workflow Guide](/ai-ide-workflow/). diff --git a/docs/guides/installation.md b/docs/guides/installation.md index 5e8b7cd..1c615a6 100644 --- a/docs/guides/installation.md +++ b/docs/guides/installation.md @@ -3,6 +3,9 @@ layout: default title: Installation nav_order: 5 permalink: /guides/installation/ +keywords: [install, setup, pip, uvx, docker] +audience: [solo, team] +expertise_level: [intermediate] --- # Installation diff --git a/docs/guides/installing-modules.md b/docs/guides/installing-modules.md index fa89c6d..b560d2e 100644 --- a/docs/guides/installing-modules.md +++ b/docs/guides/installing-modules.md @@ -3,6 +3,9 @@ layout: default title: Installing Modules permalink: /guides/installing-modules/ description: Install, list, show, enable, disable, uninstall, and upgrade SpecFact modules. +keywords: [install, modules, enable, disable, upgrade] +audience: [solo, team] +expertise_level: [intermediate] --- # Installing Modules diff --git a/docs/guides/integrations-overview.md b/docs/guides/integrations-overview.md index 5ba2b35..9f861fe 100644 --- a/docs/guides/integrations-overview.md +++ b/docs/guides/integrations-overview.md @@ -4,6 +4,9 @@ title: Integrations Overview permalink: /integrations-overview/ redirect_from: - /guides/integrations-overview/ +keywords: [integrations, overview, adapters, devops, tools] +audience: [solo, team, enterprise] +expertise_level: [intermediate] --- # Integrations Overview diff --git a/docs/guides/marketplace.md b/docs/guides/marketplace.md index b544ff9..80a5bb8 100644 --- a/docs/guides/marketplace.md +++ b/docs/guides/marketplace.md @@ -4,6 +4,9 @@ title: Marketplace Bundles nav_order: 23 permalink: /guides/marketplace/ description: Official SpecFact bundle IDs, trust tiers, and bundle dependency behavior. +keywords: [marketplace, bundles, trust, discovery, registry] +audience: [solo, team] +expertise_level: [intermediate] --- # Marketplace Bundles diff --git a/docs/guides/migration-0.16-to-0.19.md b/docs/guides/migration-0.16-to-0.19.md index c131a91..a4b774f 100644 --- a/docs/guides/migration-0.16-to-0.19.md +++ b/docs/guides/migration-0.16-to-0.19.md @@ -4,20 +4,9 @@ title: Migration 0.16 to 0.19 permalink: /migration-0.16-to-0.19/ redirect_from: - /guides/migration-0.16-to-0.19/ +keywords: [migration, upgrade, breaking-changes, version, compatibility] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. +This migration guide is no longer applicable. The CLI has been reorganized with mounted command groups. See [First Steps]({{ '/getting-started/first-steps/' | relative_url }}) for current command examples. diff --git a/docs/guides/migration-cli-reorganization.md b/docs/guides/migration-cli-reorganization.md index 6d98957..43c0604 100644 --- a/docs/guides/migration-cli-reorganization.md +++ b/docs/guides/migration-cli-reorganization.md @@ -4,31 +4,9 @@ title: Migration CLI Reorganization permalink: /migration-cli-reorganization/ redirect_from: - /guides/migration-cli-reorganization/ +keywords: [migration, cli, reorganization, commands, upgrade] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This migration guide is no longer applicable. The CLI reorganization is complete. See [First Steps]({{ '/getting-started/first-steps/' | relative_url }}) for current command examples or [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}) for the full command surface. diff --git a/docs/guides/migration-guide.md b/docs/guides/migration-guide.md index cb33936..eaccc94 100644 --- a/docs/guides/migration-guide.md +++ b/docs/guides/migration-guide.md @@ -4,31 +4,9 @@ title: Migration Guide permalink: /migration-guide/ redirect_from: - /guides/migration-guide/ +keywords: [migration, upgrade, guide, compatibility, version] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate] --- -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This migration guide is no longer applicable. All commands now use mounted command groups (e.g., `specfact backlog`, `specfact code review`). See [First Steps]({{ '/getting-started/first-steps/' | relative_url }}) for current examples or [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}) for the full command reference. diff --git a/docs/guides/module-marketplace.md b/docs/guides/module-marketplace.md index 9007294..5526368 100644 --- a/docs/guides/module-marketplace.md +++ b/docs/guides/module-marketplace.md @@ -3,6 +3,9 @@ layout: default title: Module Marketplace permalink: /guides/module-marketplace/ description: Registry model, discovery priority, trust semantics, and security checks for SpecFact modules. +keywords: [module, marketplace, registry, discovery, trust] +audience: [solo, team] +expertise_level: [intermediate] --- # Module Marketplace diff --git a/docs/guides/openspec-journey.md b/docs/guides/openspec-journey.md index 93dcbd5..bfb53e1 100644 --- a/docs/guides/openspec-journey.md +++ b/docs/guides/openspec-journey.md @@ -2,6 +2,9 @@ layout: default title: "The Journey: OpenSpec + SpecFact Integration" permalink: /guides/openspec-journey/ +keywords: [openspec, journey, integration, workflow, specfact] +audience: [solo, team] +expertise_level: [intermediate] --- # The Journey: OpenSpec + SpecFact Integration diff --git a/docs/guides/speckit-comparison.md b/docs/guides/speckit-comparison.md index 8e7a21c..3040f15 100644 --- a/docs/guides/speckit-comparison.md +++ b/docs/guides/speckit-comparison.md @@ -2,6 +2,9 @@ layout: default title: "SpecFact vs. Spec-Kit" permalink: /guides/speckit-comparison/ +keywords: [speckit, comparison, specfact, migration, differences] +audience: [solo, team] +expertise_level: [intermediate] --- # How SpecFact Compares to GitHub Spec-Kit diff --git a/docs/guides/speckit-journey.md b/docs/guides/speckit-journey.md index d9628f2..13d668e 100644 --- a/docs/guides/speckit-journey.md +++ b/docs/guides/speckit-journey.md @@ -2,6 +2,9 @@ layout: default title: "The Journey: From Spec-Kit to SpecFact" permalink: /guides/speckit-journey/ +keywords: [speckit, journey, specfact, migration, evolution] +audience: [solo, team] +expertise_level: [intermediate] --- # The Journey: From Spec-Kit to SpecFact diff --git a/docs/guides/specmatic-integration.md b/docs/guides/specmatic-integration.md index 7b75f96..5dd57f6 100644 --- a/docs/guides/specmatic-integration.md +++ b/docs/guides/specmatic-integration.md @@ -4,20 +4,9 @@ title: Specmatic Integration permalink: /specmatic-integration/ redirect_from: - /guides/specmatic-integration/ +keywords: [specmatic, integration, contract-testing, api, validation] +audience: [solo, team, enterprise] +expertise_level: [intermediate] --- -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. +This page has been replaced. Specmatic integration is now part of the Spec bundle. See [Spec Validate]({{ '/bundles/spec/validate/' | relative_url }}) for contract validation and [Spec Mock]({{ '/bundles/spec/mock/' | relative_url }}) for mock servers. diff --git a/docs/guides/team-collaboration-workflow.md b/docs/guides/team-collaboration-workflow.md index a9eaa90..5e1193d 100644 --- a/docs/guides/team-collaboration-workflow.md +++ b/docs/guides/team-collaboration-workflow.md @@ -4,6 +4,9 @@ title: Team Collaboration Workflow permalink: /team-collaboration-workflow/ redirect_from: - /guides/team-collaboration-workflow/ +keywords: [team, collaboration, workflow, personas, sharing] +audience: [solo, team] +expertise_level: [intermediate] --- # Team Collaboration Workflow diff --git a/docs/guides/template-customization.md b/docs/guides/template-customization.md index 8a308a8..18d744e 100644 --- a/docs/guides/template-customization.md +++ b/docs/guides/template-customization.md @@ -2,6 +2,9 @@ layout: default title: Template Customization Guide permalink: /guides/template-customization/ +keywords: [template, customization, configuration, output, formatting] +audience: [solo, team] +expertise_level: [intermediate] --- # Template Customization Guide diff --git a/docs/guides/testing-terminal-output.md b/docs/guides/testing-terminal-output.md index ba22b8c..c580e2a 100644 --- a/docs/guides/testing-terminal-output.md +++ b/docs/guides/testing-terminal-output.md @@ -4,6 +4,9 @@ title: Testing Terminal Output Modes permalink: /testing-terminal-output/ redirect_from: - /guides/testing-terminal-output/ +keywords: [testing, terminal, output, modes, formatting] +audience: [solo, team] +expertise_level: [intermediate] --- # Testing Terminal Output Modes diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md index 4759296..163c091 100644 --- a/docs/guides/troubleshooting.md +++ b/docs/guides/troubleshooting.md @@ -4,31 +4,9 @@ title: Troubleshooting permalink: /troubleshooting/ redirect_from: - /guides/troubleshooting/ +keywords: [troubleshooting, debugging, errors, faq, help] +audience: [solo, team] +expertise_level: [intermediate] --- -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This page has been replaced. For setup help see [Installation]({{ '/getting-started/installation/' | relative_url }}), for module verification see [Module Bootstrap Checklist]({{ '/getting-started/module-bootstrap-checklist/' | relative_url }}). diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md index 0ebd42d..56405ba 100644 --- a/docs/guides/use-cases.md +++ b/docs/guides/use-cases.md @@ -4,31 +4,9 @@ title: Use Cases permalink: /use-cases/ redirect_from: - /guides/use-cases/ +keywords: [use-cases, scenarios, examples, workflow, applications] +audience: [solo, team] +expertise_level: [intermediate] --- -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. +This page has been replaced. See [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}) for use cases per module, or [Cross-Module Chains]({{ '/guides/cross-module-chains/' | relative_url }}) for workflow examples. diff --git a/docs/guides/using-module-security-and-extensions.md b/docs/guides/using-module-security-and-extensions.md deleted file mode 100644 index fc73177..0000000 --- a/docs/guides/using-module-security-and-extensions.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: default -title: Using Module Security and Schema Extensions -permalink: /guides/using-module-security-and-extensions/ -description: How to use arch-06 (module security) and arch-07 (schema extensions) from CLI commands and as a module author. -nav_order: 22 ---- - -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/guides/ux-features.md b/docs/guides/ux-features.md index 66a3cc3..a6b7970 100644 --- a/docs/guides/ux-features.md +++ b/docs/guides/ux-features.md @@ -4,20 +4,9 @@ title: UX Features Guide permalink: /ux-features/ redirect_from: - /guides/ux-features/ +keywords: [ux, features, interface, output, usability] +audience: [solo, team] +expertise_level: [intermediate] --- -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. +This page has been replaced. For an overview of available modules and their capabilities, see [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}). diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md index 6238709..ce6f60c 100644 --- a/docs/guides/workflows.md +++ b/docs/guides/workflows.md @@ -4,6 +4,9 @@ title: Workflows permalink: /workflows/ redirect_from: - /guides/workflows/ +keywords: [workflows, automation, pipeline, chains, process] +audience: [solo, team] +expertise_level: [intermediate] --- # Workflows diff --git a/docs/index.md b/docs/index.md index 8ae717b..131e8be 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,6 +3,9 @@ layout: default title: Official SpecFact Modules Docs nav_order: 1 permalink: / +keywords: [specfact, modules, bundles, documentation, home] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate, advanced] --- # Official SpecFact Modules Docs @@ -11,19 +14,67 @@ Canonical documentation for official nold-ai bundles and module-specific workflo The modules site owns all bundle-specific deep guidance. Core CLI platform docs remain at [docs.specfact.io](https://docs.specfact.io). +**New here?** Start with [Choose Your Modules]({{ '/getting-started/choose-your-modules/' | relative_url }}) — a quick guide to what each module does, which ones you need, and how they work together. + +## Find Your Path + +
+
+

Solo Developer

+

Get started quickly with SpecFact modules on your own projects.

+ +
+
+

Small Team / Startup

+

Set up SpecFact for your team with shared configuration and agile workflows.

+ +
+
+

Corporate Team

+

Scale SpecFact across multiple repos with CI/CD integration and governance.

+ +
+
+

Enterprise

+

Enterprise-grade configuration, security, custom registries and module authoring.

+ +
+
+ ## Official Bundles -| Bundle | Overview | Deep dives | +| Bundle | Overview | Deep Dives | |--------|----------|------------| -| Backlog | [Overview](bundles/backlog/overview/) | [Refinement](bundles/backlog/refinement/), [delta](bundles/backlog/delta/), [policy](bundles/backlog/policy-engine/) | -| Project | [Overview](bundles/project/overview/) | [DevOps flow](bundles/project/devops-flow/), [import features](bundles/project/import-migration/) | -| Codebase | [Overview](bundles/codebase/overview/) | [Sidecar validation](bundles/codebase/sidecar-validation/) | -| Spec | [Overview](bundles/spec/overview/) | [Command reference](reference/commands/) | -| Govern | [Overview](bundles/govern/overview/) | [Command reference](reference/commands/) | -| Code Review | [Overview](bundles/code-review/overview/) | [Module guide](modules/code-review/) | +| Backlog | [Overview](bundles/backlog/overview/) | [Refinement](bundles/backlog/refinement/), [Delta](bundles/backlog/delta/), [Policy Engine](bundles/backlog/policy-engine/), [Dependency Analysis](bundles/backlog/dependency-analysis/) | +| Project | [Overview](bundles/project/overview/) | [DevOps Flow](bundles/project/devops-flow/), [Import & Migration](bundles/project/import-migration/) | +| Codebase | [Overview](bundles/codebase/overview/) | [Sidecar Validation](bundles/codebase/sidecar-validation/), [Analyze](bundles/codebase/analyze/), [Drift](bundles/codebase/drift/), [Repro](bundles/codebase/repro/) | +| Spec | [Overview](bundles/spec/overview/) | [Validate](bundles/spec/validate/), [Generate Tests](bundles/spec/generate-tests/), [Mock](bundles/spec/mock/) | +| Govern | [Overview](bundles/govern/overview/) | [Enforce](bundles/govern/enforce/), [Patch](bundles/govern/patch/) | +| Code Review | [Overview](bundles/code-review/overview/) | [Run](bundles/code-review/run/), [Ledger](bundles/code-review/ledger/), [Rules](bundles/code-review/rules/) | ## Getting Started +- [Choose Your Modules](getting-started/choose-your-modules/) — which module for what, side-by-side comparison - [Installation](getting-started/installation/) - [First Steps](getting-started/first-steps/) - [Module Bootstrap Checklist](getting-started/module-bootstrap-checklist/) @@ -31,14 +82,17 @@ The modules site owns all bundle-specific deep guidance. Core CLI platform docs ## Workflows +- [Cross-Module Chains](guides/cross-module-chains/) +- [Daily DevOps Routine](guides/daily-devops-routine/) +- [CI/CD Pipeline](guides/ci-cd-pipeline/) - [Backlog Refinement](bundles/backlog/refinement/) - [Project DevOps Flow](bundles/project/devops-flow/) - [DevOps Adapter Integration](integrations/devops-adapter-overview/) -## Team And Enterprise +## Team and Enterprise - [Team Collaboration Setup](team-and-enterprise/team-collaboration/) -- [Agile And Scrum Team Setup](team-and-enterprise/agile-scrum-setup/) +- [Agile and Scrum Team Setup](team-and-enterprise/agile-scrum-setup/) - [Multi-Repo Setup](team-and-enterprise/multi-repo/) - [Enterprise Configuration](team-and-enterprise/enterprise-config/) diff --git a/docs/integrations/devops-adapter-overview.md b/docs/integrations/devops-adapter-overview.md index 3a3c1d1..300766a 100644 --- a/docs/integrations/devops-adapter-overview.md +++ b/docs/integrations/devops-adapter-overview.md @@ -4,6 +4,9 @@ title: DevOps Adapter Integration Guide permalink: /integrations/devops-adapter-overview/ redirect_from: - /guides/devops-adapter-integration/ +keywords: [devops, adapter, integration, overview, pipeline] +audience: [solo, team, enterprise] +expertise_level: [intermediate] --- # DevOps Adapter Integration Guide @@ -1412,7 +1415,7 @@ Verify `openspec/changes//proposal.md` was updated: ### Related Examples -- [DevOps Integration Examples](../examples/) +- [Daily DevOps Routine](/guides/daily-devops-routine/) - DevOps workflow examples ### Architecture & Troubleshooting diff --git a/docs/module-publishing-guide.md b/docs/module-publishing-guide.md index fb13b39..cf0ddd9 100644 --- a/docs/module-publishing-guide.md +++ b/docs/module-publishing-guide.md @@ -2,6 +2,9 @@ layout: default title: Module Publishing Guide permalink: /module-publishing-guide/ +keywords: [publishing, modules, guide, registry, packaging] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Module Publishing Guide diff --git a/docs/modules/code-review.md b/docs/modules/code-review.md index 77038e7..46506a9 100644 --- a/docs/modules/code-review.md +++ b/docs/modules/code-review.md @@ -3,6 +3,9 @@ layout: default title: Code review module nav_order: 10 permalink: /modules/code-review/ +keywords: [code-review, module, review, quality, analysis] +audience: [solo, team, enterprise] +expertise_level: [intermediate, advanced] --- # specfact-code-review module notes diff --git a/docs/reference/README.md b/docs/reference/README.md index c16f149..2a22435 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -2,6 +2,9 @@ layout: default title: Reference Documentation permalink: /reference/ +keywords: [reference, documentation, index, overview, api] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Reference Documentation diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index 8dc72bd..8403805 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -2,6 +2,9 @@ layout: default title: Architecture permalink: /architecture/ +keywords: [architecture, design, modules, runtime, structure] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Architecture diff --git a/docs/reference/authentication.md b/docs/reference/authentication.md index 7d12546..0058af0 100644 --- a/docs/reference/authentication.md +++ b/docs/reference/authentication.md @@ -2,6 +2,9 @@ layout: default title: Authentication permalink: /reference/authentication/ +keywords: [authentication, auth, tokens, security, credentials] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Authentication diff --git a/docs/reference/bridge-registry.md b/docs/reference/bridge-registry.md index e7e4816..9dca38d 100644 --- a/docs/reference/bridge-registry.md +++ b/docs/reference/bridge-registry.md @@ -2,6 +2,9 @@ layout: default title: Bridge Registry permalink: /reference/bridge-registry/ +keywords: [bridge, registry, adapters, lookup, resolution] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Bridge Registry diff --git a/docs/reference/command-syntax-policy.md b/docs/reference/command-syntax-policy.md index 69b1115..a61eda9 100644 --- a/docs/reference/command-syntax-policy.md +++ b/docs/reference/command-syntax-policy.md @@ -3,6 +3,9 @@ layout: default title: Command Syntax Policy permalink: /reference/command-syntax-policy/ description: Source-of-truth policy for documenting SpecFact CLI command argument syntax. +keywords: [command-syntax, policy, documentation, arguments, conventions] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Command Syntax Policy diff --git a/docs/reference/commands.md b/docs/reference/commands.md index ac3d941..8ab86fe 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -2,6 +2,9 @@ layout: default title: Command Reference permalink: /reference/commands/ +keywords: [commands, reference, cli, syntax, usage] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Command Reference diff --git a/docs/reference/debug-logging.md b/docs/reference/debug-logging.md deleted file mode 100644 index 1a87662..0000000 --- a/docs/reference/debug-logging.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: default -title: Debug Logging -permalink: /debug-logging/ ---- - -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/reference/dependency-resolution.md b/docs/reference/dependency-resolution.md index 3ba4da9..d76aea4 100644 --- a/docs/reference/dependency-resolution.md +++ b/docs/reference/dependency-resolution.md @@ -3,6 +3,9 @@ layout: default title: Dependency resolution permalink: /reference/dependency-resolution/ description: How SpecFact resolves module and pip dependencies before install and how to bypass or override. +keywords: [dependency, resolution, modules, pip, install] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Dependency resolution diff --git a/docs/reference/directory-structure.md b/docs/reference/directory-structure.md deleted file mode 100644 index 67ca3e5..0000000 --- a/docs/reference/directory-structure.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: default -title: SpecFact CLI Directory Structure -permalink: /directory-structure/ ---- - -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/reference/documentation-url-contract.md b/docs/reference/documentation-url-contract.md index eba38f6..67bc1d0 100644 --- a/docs/reference/documentation-url-contract.md +++ b/docs/reference/documentation-url-contract.md @@ -3,6 +3,9 @@ layout: default title: Core and modules docs URL contract permalink: /reference/documentation-url-contract/ description: Ownership boundaries and published URL rules between docs.specfact.io and modules.specfact.io. +keywords: [documentation, url, contract, ownership, routing] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Core and modules documentation URL contract diff --git a/docs/reference/feature-keys.md b/docs/reference/feature-keys.md deleted file mode 100644 index 199ad63..0000000 --- a/docs/reference/feature-keys.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: default -title: Feature Keys Legacy Workflow Note -permalink: /reference/feature-keys/ ---- - -# Legacy Workflow Note - -This page referenced command groups or workflow steps that are no longer part of the current public mounted CLI in this repository. The old examples were removed to avoid directing readers to unavailable commands. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` - -For exact syntax, verify against live help in the current release before copying examples. diff --git a/docs/reference/modes.md b/docs/reference/modes.md index 62d4742..346c452 100644 --- a/docs/reference/modes.md +++ b/docs/reference/modes.md @@ -2,6 +2,9 @@ layout: default title: Operational Modes permalink: /modes/ +keywords: [modes, operational, cli, copilot, configuration] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Operational Modes diff --git a/docs/reference/module-categories.md b/docs/reference/module-categories.md index a1868c9..0ad3883 100644 --- a/docs/reference/module-categories.md +++ b/docs/reference/module-categories.md @@ -3,6 +3,9 @@ layout: default title: Module Categories nav_order: 35 permalink: /reference/module-categories/ +keywords: [module, categories, classification, types, organization] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Module Categories diff --git a/docs/reference/module-contracts.md b/docs/reference/module-contracts.md index fdb3766..311d9be 100644 --- a/docs/reference/module-contracts.md +++ b/docs/reference/module-contracts.md @@ -3,6 +3,9 @@ layout: default title: Module Contracts permalink: /reference/module-contracts/ description: ModuleIOContract protocol, validation output model, and isolation rules for module developers. +keywords: [module, contracts, protocol, validation, isolation] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Module Contracts diff --git a/docs/reference/module-security.md b/docs/reference/module-security.md index 442281d..fc5466f 100644 --- a/docs/reference/module-security.md +++ b/docs/reference/module-security.md @@ -3,6 +3,9 @@ layout: default title: Module Security permalink: /reference/module-security/ description: Trust model, checksum and signature verification, and integrity lifecycle for module packages. +keywords: [module, security, trust, checksum, signature] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Module Security diff --git a/docs/reference/parameter-standard.md b/docs/reference/parameter-standard.md deleted file mode 100644 index 3d52d70..0000000 --- a/docs/reference/parameter-standard.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: default -title: Parameter Standard Legacy Workflow Note -permalink: /reference/parameter-standard/ ---- - -# Legacy Workflow Note - -This page described older plan-generation, contract, and constitution workflows that are not part of the current public mounted CLI in this repository. The detailed command examples previously documented here were removed because they no longer match the command surface exposed by `specfact --help`. - -Use the current mounted entrypoints instead: - -- `specfact project --help` -- `specfact project sync --help` -- `specfact code --help` -- `specfact code review --help` -- `specfact spec --help` -- `specfact govern --help` -- `specfact backlog --help` -- `specfact module --help` - -When you need exact syntax, verify against live help in the current release, for example: - -```bash -specfact sync bridge --help -specfact code repro --help -specfact code validate sidecar --help -specfact spec validate --help -specfact govern enforce --help -``` - -This page needs a full rewrite around the mounted command groups before task-level workflow examples can be published again. diff --git a/docs/reference/projectbundle-schema.md b/docs/reference/projectbundle-schema.md index fe28e44..5a2cf69 100644 --- a/docs/reference/projectbundle-schema.md +++ b/docs/reference/projectbundle-schema.md @@ -3,6 +3,9 @@ layout: default title: ProjectBundle Schema permalink: /reference/projectbundle-schema/ description: ProjectBundle fields, schema_version semantics, and compatibility guidance. +keywords: [projectbundle, schema, fields, versioning, configuration] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # ProjectBundle Schema diff --git a/docs/reference/schema-versioning.md b/docs/reference/schema-versioning.md index 045af7d..010f1e9 100644 --- a/docs/reference/schema-versioning.md +++ b/docs/reference/schema-versioning.md @@ -2,6 +2,9 @@ layout: default title: Schema Versioning permalink: /schema-versioning/ +keywords: [schema, versioning, compatibility, migration, format] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Schema Versioning diff --git a/docs/reference/specmatic.md b/docs/reference/specmatic.md index 9d8fd94..f7b17d5 100644 --- a/docs/reference/specmatic.md +++ b/docs/reference/specmatic.md @@ -2,6 +2,9 @@ layout: default title: Specmatic API Reference permalink: /reference/specmatic/ +keywords: [specmatic, api, reference, contract-testing, validation] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Specmatic API Reference diff --git a/docs/reference/telemetry.md b/docs/reference/telemetry.md index 3b9da3e..2c199f4 100644 --- a/docs/reference/telemetry.md +++ b/docs/reference/telemetry.md @@ -2,6 +2,9 @@ layout: default title: Privacy-First Telemetry permalink: /reference/telemetry/ +keywords: [telemetry, privacy, analytics, opt-out, data] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Privacy-First Telemetry (Optional) diff --git a/docs/reference/thorough-codebase-validation.md b/docs/reference/thorough-codebase-validation.md index 1d6e28f..12be784 100644 --- a/docs/reference/thorough-codebase-validation.md +++ b/docs/reference/thorough-codebase-validation.md @@ -3,6 +3,9 @@ layout: default title: Thorough Codebase Validation permalink: /reference/thorough-codebase-validation/ description: How to run in-depth validation (quick check, contract-decorated, sidecar, dogfooding). +keywords: [validation, codebase, thorough, contract, dogfooding] +audience: [solo, team, enterprise] +expertise_level: [advanced] --- # Thorough Codebase Validation diff --git a/docs/team-and-enterprise/agile-scrum-setup.md b/docs/team-and-enterprise/agile-scrum-setup.md index 34b8a19..cad22a4 100644 --- a/docs/team-and-enterprise/agile-scrum-setup.md +++ b/docs/team-and-enterprise/agile-scrum-setup.md @@ -4,6 +4,9 @@ title: Agile And Scrum Team Setup permalink: /team-and-enterprise/agile-scrum-setup/ redirect_from: - /guides/agile-scrum-workflows/ +keywords: [agile, scrum, team, setup, ceremonies] +audience: [team, enterprise] +expertise_level: [intermediate] --- # Agile And Scrum Team Setup diff --git a/docs/team-and-enterprise/enterprise-config.md b/docs/team-and-enterprise/enterprise-config.md index d232b97..79271d9 100644 --- a/docs/team-and-enterprise/enterprise-config.md +++ b/docs/team-and-enterprise/enterprise-config.md @@ -2,6 +2,9 @@ layout: default title: Enterprise Configuration permalink: /team-and-enterprise/enterprise-config/ +keywords: [enterprise, configuration, admin, policy, organization] +audience: [team, enterprise] +expertise_level: [intermediate] --- # Enterprise Configuration diff --git a/docs/team-and-enterprise/multi-repo.md b/docs/team-and-enterprise/multi-repo.md index ef8a8d4..bbc854a 100644 --- a/docs/team-and-enterprise/multi-repo.md +++ b/docs/team-and-enterprise/multi-repo.md @@ -2,6 +2,9 @@ layout: default title: Multi-Repo Setup permalink: /team-and-enterprise/multi-repo/ +keywords: [multi-repo, monorepo, setup, enterprise, organization] +audience: [team, enterprise] +expertise_level: [intermediate] --- # Multi-Repo Setup diff --git a/docs/team-and-enterprise/team-collaboration.md b/docs/team-and-enterprise/team-collaboration.md index 7f66a13..bad10b6 100644 --- a/docs/team-and-enterprise/team-collaboration.md +++ b/docs/team-and-enterprise/team-collaboration.md @@ -4,6 +4,9 @@ title: Team Collaboration Setup permalink: /team-and-enterprise/team-collaboration/ redirect_from: - /guides/team-collaboration-workflow/ +keywords: [team, collaboration, sharing, personas, workflow] +audience: [team, enterprise] +expertise_level: [intermediate] --- # Team Collaboration Setup diff --git a/openspec/CHANGE_ORDER.md b/openspec/CHANGE_ORDER.md index f922699..5ed864d 100644 --- a/openspec/CHANGE_ORDER.md +++ b/openspec/CHANGE_ORDER.md @@ -60,6 +60,7 @@ Cross-repo dependency: `docs-06-modules-site-ia-restructure` is a prerequisite f | docs | 10 | docs-10-workflow-consolidation | [#98](https://github.com/nold-ai/specfact-cli-modules/issues/98) | docs-06-modules-site-ia-restructure | | docs | 11 | docs-11-team-enterprise-tier | [#99](https://github.com/nold-ai/specfact-cli-modules/issues/99) | docs-06-modules-site-ia-restructure | | docs | 12 | docs-12-docs-validation-ci | [#100](https://github.com/nold-ai/specfact-cli-modules/issues/100) | docs-06 through docs-10; specfact-cli/docs-12-docs-validation-ci | +| docs | 13 | docs-13-nav-search-theme-roles | [#123](https://github.com/nold-ai/specfact-cli-modules/issues/123) | docs-06 through docs-12 (fixes navigation gaps left by prior changes; adds search, theme toggle, and role-based navigation) | ### Spec-Kit v0.4.x change proposal bridge (spec-kit integration review, 2026-03-27) diff --git a/openspec/changes/docs-13-nav-search-theme-roles/.openspec.yaml b/openspec/changes/docs-13-nav-search-theme-roles/.openspec.yaml new file mode 100644 index 0000000..65bf7c9 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-28 diff --git a/openspec/changes/docs-13-nav-search-theme-roles/TDD_EVIDENCE.md b/openspec/changes/docs-13-nav-search-theme-roles/TDD_EVIDENCE.md new file mode 100644 index 0000000..4e480bc --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/TDD_EVIDENCE.md @@ -0,0 +1,157 @@ +# docs-13 Validation Evidence + +Date: 2026-03-28T21:57:34+01:00 + +## Implementation state recovered from Claude session + +- Claude session `fff31fcf-cd55-4952-896b-638cb0e8958f` worked in git worktree `/../specfact-cli-modules-worktrees/feature/docs-13-nav-search-theme-roles` +- Session artifacts showed completed implementation across `docs/_layouts/default.html`, `docs/assets/main.scss`, new `_data`, `_includes`, `assets/js`, and bulk front matter enrichment +- Remaining incomplete scope at handoff was validation task group `7` + +## Red phase + +### 1. Failing markdown lint review on OpenSpec docs artifacts + +Command: + +```bash +markdownlint openspec/changes/docs-13-nav-search-theme-roles/**/*.md +``` + +Result: + +```text +openspec/changes/docs-13-nav-search-theme-roles/tasks.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading +openspec/changes/docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading +openspec/changes/docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md:3 MD022/blanks-around-headings Headings should be surrounded by blank lines +openspec/changes/docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading +openspec/changes/docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading +``` + +### 2. Failing docs robustness review before hardening fixes + +Command: + +```bash +review-check docs/_includes/breadcrumbs.html docs/_layouts/default.html docs/assets/js/search.js docs/assets/js/filters.js scripts/check-docs-commands.py +``` + +Result: + +```text +- breadcrumbs current-page detection depends on forloop.last and breaks for trailing-slash URLs +- mermaid rerender targets nested svg elements instead of only .mermaid containers +- search rendering injects unescaped doc data via innerHTML and assumes fetch/lunr always succeed +- expertise persistence uses unguarded localStorage.getItem/setItem +- _validate_nav_data_links can raise yaml.YAMLError instead of emitting a validation finding +``` + +## Validation commands + +### 1. Docs command + nav validation + +Command: + +```bash +python3 scripts/check-docs-commands.py +``` + +Result: + +```text +Docs command validation passed with no findings. +``` + +Notes: + +- Extended validator to check `_data/nav.yml` URLs against actual docs routes +- Excluded `docs/vendor/**` and `docs/_site/**` from markdown validation set + +### 2. Jekyll build + +Command: + +```bash +cd docs && bundle exec jekyll build +``` + +Result: + +```text +Configuration file: /../specfact-cli-modules-worktrees/feature/docs-13-nav-search-theme-roles/docs/_config.yml + Source: /../specfact-cli-modules-worktrees/feature/docs-13-nav-search-theme-roles/docs + Destination: /../specfact-cli-modules-worktrees/feature/docs-13-nav-search-theme-roles/docs/_site + Generating... + done in 0.924 seconds. + Auto-regeneration: disabled. Use --watch to enable. +``` + +## Manual browser verification against built site + +Served local build: + +```bash +cd docs/_site && python3 -m http.server 4013 +``` + +Verified in browser at `http://127.0.0.1:4013/`: + +- Sidebar rendered all sections and bundle groups from `_data/nav.yml` +- Sidebar links resolved to generated local routes including: + - `/bundles/govern/overview/` + - `/bundles/code-review/overview/` + - `/guides/cross-module-chains/` + - `/team-and-enterprise/enterprise-config/` + - `/reference/commands/` +- Search query `govern` returned 10 results including: + - `Govern enforce` + - `Govern bundle overview` + - `Govern patch apply` +- Expertise filter `advanced` reduced visible nav items from `67` to `43` and persisted in `localStorage` as `specfact-expertise=advanced` +- Theme toggle switched to `light` and persisted across reload via `localStorage` as `specfact-theme=light` + +## Additional notes + +- Search widget was hardened to fetch the search index from a `relative_url`-aware attribute rather than a hard-coded absolute path +- Legitimate in-content references to `/reference/commands/` remain in docs body content; validation for task `7.3` refers to the sidebar navigation replacing stale placeholder bundle links, which is satisfied + +## Final quality gates + +Date: 2026-03-28T22:28:03+01:00 + +Commands: + +```bash +hatch run format +hatch run type-check +hatch run lint +hatch run yaml-lint +hatch run check-bundle-imports +hatch run verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump +hatch run contract-test +hatch run smart-test +hatch run test +openspec validate docs-13-nav-search-theme-roles --strict +``` + +Result summary: + +- `format`: passed +- `type-check`: `0 errors, 0 warnings, 0 notes` +- `lint`: passed, `pylint` rated `10.00/10` +- `yaml-lint`: passed, validated `6` manifests plus `registry/index.json` +- `check-bundle-imports`: passed +- `verify-modules-signature --require-signature --payload-from-filesystem --enforce-version-bump`: passed for all `6` module manifests +- `contract-test`: `462 passed, 1 warning` +- `smart-test`: `462 passed, 1 warning` +- `test`: `462 passed, 1 warning` +- `openspec validate docs-13-nav-search-theme-roles --strict`: passed + +Warnings: + +- The docs review suite still reports `7` pre-existing authored-link warnings in non-restructured legacy pages under `docs/adapters/` and `docs/reference/`; these are warning-only and did not block any gate + +Fixes completed during gate run: + +- Restored `/guides/ide-integration/` as a redirect page to `/ai-ide-workflow/` so restructured bundle pages no longer point at a missing published route +- Updated the modules docs layout markup to keep the sidebar section scope explicit for the contract test while preserving the rendered data-driven navigation diff --git a/openspec/changes/docs-13-nav-search-theme-roles/design.md b/openspec/changes/docs-13-nav-search-theme-roles/design.md new file mode 100644 index 0000000..6505d5b --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/design.md @@ -0,0 +1,132 @@ +## Context + +The modules documentation site (`modules.specfact.io`) is a Jekyll 4.3 static site using the Minima 2.5 theme with heavy CSS customization. The sidebar navigation is hardcoded in `docs/_layouts/default.html` (265 lines). Six OpenSpec changes (docs-06 through docs-12) created ~24 new markdown pages across bundles, workflows, and team/enterprise sections, but the sidebar HTML was never updated to link to them. Three bundle sections (Code Review, Spec, Govern) link to a generic `/reference/commands/` placeholder. The homepage `index.md` has the same stale links. + +The site is dark-mode-only (despite `skin: auto` in minima config), has no search functionality, and offers no way for users to filter content by their role or expertise level. The current styling, while functional, is visually heavy with high-contrast cyan accents that can be distracting for extended reading. + +Key constraints: Jekyll static site (no server-side rendering), existing `redirect_from` entries must be preserved, cross-site links from `docs.specfact.io` must not break, and the SpecFact brand identity (cyan/teal accent on dark navy) must be maintained. + +## Goals / Non-Goals + +**Goals:** +- Fix every broken or stale sidebar and homepage link +- Make navigation data-driven to prevent future sidebar drift +- Add professional light/dark mode toggle with SpecFact brand colors +- Add client-side keyword search over front matter metadata +- Add expertise-level filtering and role-based homepage entry points +- Improve overall readability and reduce visual distraction +- Active-page highlighting and breadcrumbs for orientation + +**Non-Goals:** +- Changing any existing page URLs or permalink structures +- Server-side search or external search service integration (Algolia, etc.) +- Restructuring the information architecture (already done in docs-06) +- Adding new documentation content beyond navigation/UX improvements +- Modifying the specfact-cli docs site (`docs.specfact.io`) + +## Decisions + +### D1: Data-driven navigation via `_data/nav.yml` + +**Choice**: Extract all sidebar links into `docs/_data/nav.yml` and render via `docs/_includes/sidebar-nav.html` using Liquid loops. + +**Why over hardcoded HTML**: The root cause of the broken links is that docs-09/10/11 created pages but nobody updated the hardcoded sidebar. A data file is easier to review, diff, and validate in CI. The `check-docs-commands.py` script can be extended to verify nav.yml targets exist. + +**Why over Jekyll's built-in collection navigation**: Minima's auto-nav doesn't support the nested bundle `
` structure we need. A data file gives full control over grouping, ordering, and collapsible sections. + +**Structure**: +```yaml +- section: Getting Started + items: + - title: Installation + url: /getting-started/installation/ +- section: Bundles + bundles: + - name: Backlog + items: + - title: Overview + url: /bundles/backlog/overview/ +``` + +### D2: Theme toggle via `[data-theme]` attribute on `` + +**Choice**: Use `data-theme="light"` / `data-theme="dark"` attribute on the `` element, with a `theme.js` script loaded in `` (before body renders) to prevent flash of wrong theme (FOUC). + +**Why over CSS `prefers-color-scheme` only**: Users want explicit control. `skin: auto` in minima config provides system-preference fallback, but a toggle button gives direct control. `localStorage` persists the choice. + +**Why over class-based toggling**: `[data-theme]` works natively with CSS `color-scheme` property and is the modern standard pattern. + +**Color palette**: +- Dark mode: Current colors with slightly subdued cyan (`#57e6c4` instead of `#64ffda`) for reduced eye strain +- Light mode: `#ffffff` background, `#1a1a2e` text, `#0d9488` (teal-600) as accent — retains SpecFact brand identity in a readable light context + +### D3: Lunr.js for client-side search + +**Choice**: Lunr.js loaded from CDN (~8 KB gzipped), with a Jekyll Liquid-generated `search-index.json` that includes `url`, `title`, `keywords`, `audience`, `expertise_level`, and a content snippet per page. + +**Why Lunr.js over alternatives**: +- No server required (pure client-side, works offline) +- Standard for Jekyll sites (well-documented integration) +- Small footprint, lazy-loaded on first search focus +- Supports field boosting (title: 10x, keywords: 5x, content: 1x) + +**Why not Algolia/Pagefind**: Algolia requires external service account and API keys. Pagefind requires a build step binary. Both are overkill for ~100 pages. + +**Search index**: Generated at build time as `docs/assets/js/search-index.json` using Liquid template with Jekyll frontmatter. + +### D4: Expertise filter as single dropdown, not dual filters + +**Choice**: Single expertise-level dropdown (All / Beginner / Intermediate / Advanced) in the sidebar, above the navigation sections. No separate audience filter in the sidebar. + +**Why single filter**: Two dropdowns (expertise + audience) make the sidebar cluttered. The audience dimension (solo/team/enterprise) is better served by the homepage "Find Your Path" cards which link to curated page sets. The expertise filter directly controls sidebar visibility using `data-expertise` attributes on nav items. + +**Implementation**: Each nav item in `nav.yml` carries an `expertise` field. The filter JS adds/removes a CSS class on the sidebar that hides non-matching items. Stored in `localStorage`. + +### D5: Front matter enrichment strategy + +**Choice**: Add three new optional fields to all doc page front matter: +```yaml +keywords: [search, terms, here] +audience: [solo, team, enterprise] +expertise_level: [beginner, intermediate, advanced] +``` + +**Assignment logic**: +- Getting Started pages: `expertise_level: [beginner]`, `audience: [solo, team, enterprise]` +- Bundle overviews: `expertise_level: [beginner, intermediate]`, `audience: [solo, team, enterprise]` +- Command deep dives: `expertise_level: [intermediate, advanced]`, `audience: [solo, team, enterprise]` +- Workflows: `expertise_level: [intermediate]`, `audience: [solo, team]` +- Team & Enterprise: `expertise_level: [intermediate]`, `audience: [team, enterprise]` +- Authoring: `expertise_level: [advanced]`, `audience: [solo, team, enterprise]` +- Reference: `expertise_level: [advanced]`, `audience: [solo, team, enterprise]` + +### D6: Mermaid theme-awareness + +**Choice**: Refactor the inline `mermaid.initialize()` call into a `initMermaid(theme)` function. On theme toggle, re-initialize mermaid with appropriate `themeVariables` for light or dark mode. Light mode uses mermaid's `default` theme with SpecFact teal accents. + +### D7: File organization + +**New directories and files**: +``` +docs/ +├── _data/nav.yml # navigation data +├── _includes/ +│ ├── sidebar-nav.html # nav renderer +│ ├── search.html # search UI +│ ├── theme-toggle.html # toggle button +│ ├── expertise-filter.html # filter dropdown +│ └── breadcrumbs.html # page breadcrumbs +└── assets/js/ + ├── theme.js # theme toggle + persistence + ├── search.js # Lunr.js integration + ├── search-index.json # Liquid-generated index + └── filters.js # expertise filter logic +``` + +## Risks / Trade-offs + +- **[Mermaid re-rendering on theme toggle]** → Mermaid.js re-init can cause a brief flash. Mitigation: wrap diagrams in a container that fades out/in during re-render. +- **[Search index size]** → With ~100 pages and content snippets, index could be 50-100 KB. Mitigation: truncate content to first 200 words per page; lazy-load on first search focus. +- **[Front matter bulk update risk]** → Touching ~50 files increases merge conflict surface. Mitigation: front matter additions are purely additive (new keys only); no existing keys changed. +- **[Light mode readability of existing content]** → Some pages may have inline color references or assumptions about dark backgrounds. Mitigation: audit all pages with embedded HTML/style tags during implementation. +- **[Expertise filter hiding content]** → Users might not realize content is filtered. Mitigation: show count of visible/total items and a "showing filtered results" indicator. diff --git a/openspec/changes/docs-13-nav-search-theme-roles/proposal.md b/openspec/changes/docs-13-nav-search-theme-roles/proposal.md new file mode 100644 index 0000000..acf7258 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/proposal.md @@ -0,0 +1,36 @@ +## Why + +The docs-06 through docs-12 changes created per-bundle command pages, overview pages, workflow consolidation, and team/enterprise documentation, but the sidebar navigation in `default.html` was never updated to link to these new pages. Three bundles (Code Review, Spec, Govern) still point to a generic `/reference/commands/` page, Codebase is missing three command pages, Team & Enterprise links to stale paths, and the Workflows section omits four new guides. The homepage `index.md` has the same stale-link problem. Beyond broken navigation, the site lacks a light/dark mode toggle, client-side search, and role/expertise-based navigation that would help different user profiles (solo developer through enterprise) find relevant content quickly. + +## What Changes + +- **Fix all broken sidebar links**: update Code Review, Spec, Govern, and Codebase bundle sections to link to their actual command pages instead of `/reference/commands/`; add Overview links to every bundle; fix Team & Enterprise stale paths; add missing Workflow pages (cross-module-chains, daily-devops-routine, ci-cd-pipeline, brownfield-modernization) +- **Fix homepage stale links**: update `index.md` bundle table deep-dive links for Spec, Govern, and Code Review +- **Extract navigation into data file**: move hardcoded sidebar HTML into `_data/nav.yml` rendered via `_includes/sidebar-nav.html` to prevent future drift +- **Add light/dark mode toggle**: dual CSS theme with `[data-theme]` attribute, localStorage persistence, theme-aware Mermaid re-rendering, and light-mode Rouge syntax highlighting +- **Add client-side search**: Lunr.js-powered search with a Jekyll-generated index from front matter metadata (title, keywords, audience, expertise_level); keyboard shortcuts (Ctrl+K / Cmd+K); dropdown results with snippets +- **Add role/expertise navigation**: sidebar expertise-level filter (beginner / intermediate / advanced); homepage "Find Your Path" section with role-based entry cards (solo, startup, corporate, enterprise) +- **Enrich front matter metadata**: add `keywords`, `audience`, and `expertise_level` fields to all doc pages +- **Refine theme**: cleaner sidebar visual weight, improved code block contrast, active-page highlighting, breadcrumbs for orientation, support for both light and dark modes + +## Capabilities + +### New Capabilities +- `docs-nav-data-driven`: data-driven sidebar navigation via `_data/nav.yml` with correct links for all bundles, workflows, team/enterprise, and reference pages +- `docs-theme-toggle`: light/dark mode toggle with localStorage persistence, dual CSS theme, theme-aware Mermaid and syntax highlighting +- `docs-client-search`: Lunr.js client-side search powered by front matter metadata index, keyboard shortcuts, and result snippets +- `docs-role-expertise-nav`: expertise-level sidebar filter and homepage role-based entry cards for solo/startup/corporate/enterprise profiles +### Modified Capabilities +- `bundle-overview-pages`: sidebar links updated to point to actual overview and command pages instead of generic commands reference +- `modules-homepage-overview`: bundle overview section updated to surface corrected deep-dive links and role-based entry paths +- `cross-module-workflow-docs`: sidebar Workflows section updated to include all docs-10 deliverables +- `team-setup-docs`: sidebar Team & Enterprise section updated to use correct `/team-and-enterprise/` paths and include all docs-11 deliverables +- `modules-docs-command-validation`: CI validation script may need updates to cover new `_data/nav.yml` link targets and enriched front matter fields + +## Impact + +- **Files modified**: `docs/_layouts/default.html`, `docs/assets/main.scss`, `docs/_config.yml`, `docs/index.md`, ~50+ `docs/**/*.md` (front matter only) +- **New files**: `docs/_data/nav.yml`, `docs/_includes/{sidebar-nav,search,theme-toggle,expertise-filter,breadcrumbs}.html`, `docs/assets/js/{theme,search,filters}.js`, `docs/assets/js/search-index.json` +- **Dependencies**: Lunr.js loaded from CDN (~8 KB gzipped) +- **No URL changes**: all existing `redirect_from` entries preserved; cross-site links from `docs.specfact.io` unaffected +- **Cross-site**: `docs/reference/documentation-url-contract.md` unchanged diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/bundle-overview-pages/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/bundle-overview-pages/spec.md new file mode 100644 index 0000000..75e1892 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/bundle-overview-pages/spec.md @@ -0,0 +1,40 @@ +## MODIFIED Requirements + +### Requirement: Bundle overview pages SHALL provide complete bundle entry points + +Each official bundle SHALL have a single overview page that lists its commands, prerequisites, examples, and relevant bundle-owned resource setup guidance. The sidebar navigation SHALL link to each bundle's overview page as the first item in that bundle's collapsible section, and all command deep-dive pages SHALL be listed below the overview. + +#### Scenario: Overview page lists all bundle commands + +- **GIVEN** a bundle overview page such as `bundles/backlog/overview.md` +- **WHEN** a user reads the page +- **THEN** every registered command and subcommand for that bundle is listed +- **AND** each command has a brief description + +#### Scenario: Overview page includes quick examples + +- **GIVEN** a bundle overview page +- **WHEN** a user reads the page +- **THEN** at least one practical example is shown for each major command group + +#### Scenario: Overview page explains bundle-owned resource setup when relevant + +- **GIVEN** a bundle overview page for a bundle that ships prompts or workspace templates +- **WHEN** a user reads the page +- **THEN** the page explains which resources are bundled with that package +- **AND** it points to the supported setup flow such as `specfact init ide` or bundle-specific template/bootstrap commands + +#### Scenario: Command examples match actual CLI + +- **GIVEN** a command example in an overview page +- **WHEN** compared against the actual `specfact --help` output +- **THEN** the command name, arguments, and key options match +- **AND** `tests/unit/docs/test_bundle_overview_cli_examples.py::test_validate_bundle_overview_cli_help_examples` exercises each quick-example line by invoking the corresponding bundle Typer app with `--help` (or an explicit `--help` normalization for lines that include runnable flags), failing when help output cannot be produced + +#### Scenario: Sidebar links to overview and all command pages + +- **GIVEN** the sidebar navigation for any bundle (Backlog, Project, Codebase, Spec, Govern, Code Review) +- **WHEN** the bundle section is expanded +- **THEN** the first link SHALL be the bundle's overview page +- **AND** subsequent links SHALL point to each command deep-dive page under that bundle's directory +- **AND** no link SHALL point to the generic `/reference/commands/` placeholder diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/cross-module-workflow-docs/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/cross-module-workflow-docs/spec.md new file mode 100644 index 0000000..e9f455e --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/cross-module-workflow-docs/spec.md @@ -0,0 +1,34 @@ +# Specs - Cross Module Workflow Docs + +## MODIFIED Requirements + +### Requirement: Workflow docs SHALL cover current cross-module flows and setup prerequisites + +Workflow documentation SHALL show valid multi-bundle command chains and include resource-bootstrap steps when migrated bundle-owned prompts or templates are prerequisites. The sidebar Workflows section SHALL link to all workflow pages. + +#### Scenario: Cross-module chain covers full lifecycle + +- **GIVEN** the `cross-module-chains` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows a complete flow such as backlog ceremony -> code import -> spec validate -> govern enforce +- **AND** each step shows the exact command with practical arguments + +#### Scenario: Workflow docs explain resource bootstrap before dependent flows + +- **GIVEN** a workflow doc that uses AI IDE prompts or backlog workspace templates +- **WHEN** a user reads the page +- **THEN** the workflow includes the supported resource bootstrap step such as `specfact init ide` +- **AND** it does not rely on legacy core-owned resource paths + +#### Scenario: CI pipeline doc covers automation patterns + +- **GIVEN** the `ci-cd-pipeline` workflow doc +- **WHEN** a user reads the page +- **THEN** it shows pre-commit hooks, GitHub Actions integration, and CI/CD stage mapping +- **AND** all SpecFact commands shown are valid and current + +#### Scenario: Sidebar Workflows section links to all workflow pages + +- **WHEN** the Workflows section is rendered in the sidebar +- **THEN** it SHALL include links to Cross-Module Chains, Daily DevOps Routine, CI/CD Pipeline, and Brownfield Modernization +- **AND** it SHALL include links to existing workflow pages (Agile & Scrum, Command Chains, Common Tasks, Copilot Mode, Contract Testing) diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md new file mode 100644 index 0000000..9165cb1 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-client-search/spec.md @@ -0,0 +1,73 @@ +# Specs - Docs Client Search + +## ADDED Requirements + +### Requirement: Search index generation + +A Jekyll Liquid template at `docs/assets/js/search-index.json` SHALL generate a JSON array at build time containing one entry per page with fields: `url`, `title`, `keywords` (from front matter), `audience`, `expertise_level`, and `content` (page content truncated to the first 200 words with HTML tags stripped). + +#### Scenario: Search index contains all pages + +- **WHEN** the Jekyll site is built +- **THEN** the generated `search-index.json` SHALL contain entries for every page that has a `title` in its front matter + +#### Scenario: Search index includes front matter metadata + +- **WHEN** a page has `keywords: [backlog, refinement, sprint]` in its front matter +- **THEN** its search index entry SHALL include those keywords in the `keywords` field + +### Requirement: Search UI in sidebar + +A search input field SHALL be rendered in the sidebar above the navigation sections via `docs/_includes/search.html`. The search input SHALL have placeholder text "Search docs... (Ctrl+K)". + +#### Scenario: Search input is visible + +- **WHEN** any page loads +- **THEN** a search input field SHALL appear at the top of the sidebar, above all navigation sections + +#### Scenario: Keyboard shortcut focuses search + +- **WHEN** the user presses Ctrl+K (or Cmd+K on macOS) +- **THEN** the search input SHALL receive focus + +### Requirement: Lunr.js search integration + +The search SHALL use Lunr.js loaded from CDN. The search index SHALL be lazy-loaded on first search input focus. Lunr SHALL be configured with field boosting: title at 10x, keywords at 5x, content at 1x. + +#### Scenario: First search triggers index load + +- **WHEN** the user focuses the search input for the first time +- **THEN** the `search-index.json` SHALL be fetched and a Lunr index SHALL be built + +#### Scenario: Search results appear on input + +- **WHEN** the user types at least 2 characters in the search input +- **THEN** a dropdown SHALL appear below the search input showing matching results with page title and a content snippet + +#### Scenario: No results message + +- **WHEN** the user's query matches no pages +- **THEN** the dropdown SHALL show "No results found" + +### Requirement: Search result navigation + +The search results dropdown SHALL support keyboard navigation with arrow keys and Enter to follow a link. Clicking a result SHALL navigate to that page. + +#### Scenario: Arrow key navigation + +- **WHEN** the search dropdown is open and the user presses the down arrow +- **THEN** the next result SHALL be highlighted + +#### Scenario: Enter navigates to result + +- **WHEN** a result is highlighted and the user presses Enter +- **THEN** the browser SHALL navigate to that result's URL + +### Requirement: Search results show metadata tags + +Each search result SHALL display matching front matter tags (audience, expertise_level) as small pills/badges alongside the title. + +#### Scenario: Result shows audience tag + +- **WHEN** a search result is for a page with `audience: [team, enterprise]` +- **THEN** the result SHALL display "team" and "enterprise" as tag pills diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md new file mode 100644 index 0000000..d52c6ed --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-nav-data-driven/spec.md @@ -0,0 +1,93 @@ +# Specs - Navigation Data Driven + +## ADDED Requirements + +### Requirement: Navigation data file + +The sidebar navigation structure SHALL be defined in `docs/_data/nav.yml` as a YAML data file. Each top-level entry SHALL have a `section` name and either an `items` array (flat list) or a `bundles` array (collapsible groups). Each item SHALL have `title`, `url`, and optionally `expertise` fields. + +#### Scenario: Nav data file defines all sections + +- **WHEN** the `_data/nav.yml` file is loaded +- **THEN** it SHALL contain entries for all seven sections: Getting Started, Bundles, Workflows, Integrations, Team & Enterprise, Authoring, Reference + +#### Scenario: Bundle section uses collapsible groups + +- **WHEN** the Bundles section is defined in `nav.yml` +- **THEN** it SHALL use a `bundles` array with entries for Backlog, Project, Codebase, Code Review, Spec, and Govern, each containing an `items` array + +### Requirement: Sidebar nav rendered from data + +The sidebar navigation in `docs/_layouts/default.html` SHALL render navigation by including `docs/_includes/sidebar-nav.html` which iterates over `site.data.nav` using Liquid loops. Hardcoded navigation HTML SHALL be removed. + +#### Scenario: Sidebar renders all nav items + +- **WHEN** a page loads with the default layout +- **THEN** the sidebar SHALL display all sections and items defined in `nav.yml` + +#### Scenario: Bundle sections render as collapsible details + +- **WHEN** a bundle group is rendered +- **THEN** it SHALL use `
` HTML elements with the bundle name as `` + +### Requirement: All bundle links point to actual pages + +Every bundle navigation link SHALL point to an existing page URL, not to the generic `/reference/commands/` placeholder. + +#### Scenario: Code Review bundle links + +- **WHEN** the Code Review bundle section is expanded +- **THEN** it SHALL contain links to Overview, Run, Ledger, and Rules pages at their `/bundles/code-review/` paths + +#### Scenario: Spec bundle links + +- **WHEN** the Spec bundle section is expanded +- **THEN** it SHALL contain links to Overview, Validate, Generate Tests, and Mock pages at their `/bundles/spec/` paths + +#### Scenario: Govern bundle links + +- **WHEN** the Govern bundle section is expanded +- **THEN** it SHALL contain links to Overview, Enforce, and Patch pages at their `/bundles/govern/` paths + +#### Scenario: Codebase bundle links + +- **WHEN** the Codebase bundle section is expanded +- **THEN** it SHALL contain links to Overview, Sidecar Validation, Analyze, Drift, and Repro pages at their `/bundles/codebase/` paths + +### Requirement: Active page highlighting + +The sidebar SHALL highlight the currently active page by matching `page.url` against nav item URLs and applying a CSS active class. + +#### Scenario: Current page is highlighted + +- **WHEN** a user visits `/bundles/spec/validate/` +- **THEN** the Validate link in the Spec bundle section SHALL have the active CSS class applied +- **AND** the Spec bundle `
` element SHALL be in the open state + +### Requirement: Team & Enterprise links use correct paths + +The Team & Enterprise section SHALL link to pages under `/team-and-enterprise/` with all four deliverables from docs-11. + +#### Scenario: Team & Enterprise navigation completeness + +- **WHEN** the Team & Enterprise section is rendered +- **THEN** it SHALL contain links to Team Collaboration, Agile & Scrum Setup, Multi-Repo Setup, and Enterprise Configuration at their `/team-and-enterprise/` paths + +### Requirement: Workflows section includes all docs-10 pages + +The Workflows section SHALL include links to all workflow pages created in docs-10. + +#### Scenario: Workflows navigation completeness + +- **WHEN** the Workflows section is rendered +- **THEN** it SHALL contain links to Cross-Module Chains, Daily DevOps Routine, CI/CD Pipeline, and Brownfield Modernization in addition to existing workflow links + +### Requirement: Breadcrumb navigation above content + +Each page SHALL display a breadcrumb trail above the content area, derived from the page URL segments, to provide orientation and allow quick navigation to parent sections. + +#### Scenario: Bundle command page shows breadcrumb trail + +- **WHEN** a user visits `/bundles/spec/validate/` +- **THEN** a breadcrumb trail SHALL be displayed showing: Home > Bundles > Spec > Validate +- **AND** each breadcrumb segment except the current page SHALL be a clickable link diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-role-expertise-nav/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-role-expertise-nav/spec.md new file mode 100644 index 0000000..7f5d342 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-role-expertise-nav/spec.md @@ -0,0 +1,54 @@ +## ADDED Requirements + +### Requirement: Expertise level filter in sidebar +A compact dropdown or pill filter SHALL be rendered in the sidebar between the search input and the navigation sections via `docs/_includes/expertise-filter.html`. Options: All, Beginner, Intermediate, Advanced. + +#### Scenario: Filter defaults to All +- **WHEN** a user visits the site for the first time +- **THEN** the expertise filter SHALL be set to "All" and all nav items SHALL be visible + +#### Scenario: Filter hides non-matching items +- **WHEN** the user selects "Beginner" from the expertise filter +- **THEN** nav items whose `expertise` field does not include "beginner" SHALL be hidden via CSS +- **AND** bundle `
` sections with no visible items SHALL also be hidden + +#### Scenario: Filter persists across pages +- **WHEN** the user selects "Advanced" and navigates to another page +- **THEN** the filter SHALL still be set to "Advanced" (stored in `localStorage` under key `specfact-expertise`) + +#### Scenario: Filtered count indicator +- **WHEN** the expertise filter is set to a value other than "All" +- **THEN** a small indicator SHALL show how many items are visible vs total (e.g., "12 of 45") + +### Requirement: Front matter expertise and audience fields +All documentation pages SHALL have `keywords`, `audience`, and `expertise_level` fields in their front matter. These fields are arrays of strings. + +#### Scenario: Getting started pages are tagged as beginner +- **WHEN** a page under `getting-started/` is inspected +- **THEN** its front matter SHALL include `expertise_level: [beginner]` + +#### Scenario: Authoring pages are tagged as advanced +- **WHEN** a page under `authoring/` is inspected +- **THEN** its front matter SHALL include `expertise_level: [advanced]` + +#### Scenario: Team & Enterprise pages target team and enterprise audiences +- **WHEN** a page under `team-and-enterprise/` is inspected +- **THEN** its front matter SHALL include `audience: [team, enterprise]` + +### Requirement: Homepage role-based entry cards +The `index.md` homepage SHALL include a "Find Your Path" section with four role-based entry cards: Solo Developer, Small Team (Startup), Corporate Team, and Enterprise. Each card SHALL link to 3-4 curated pages most relevant to that profile. + +#### Scenario: Solo developer card content +- **WHEN** the homepage is rendered +- **THEN** the Solo Developer card SHALL link to getting started, first steps, and a bundle quickstart tutorial + +#### Scenario: Enterprise card content +- **WHEN** the homepage is rendered +- **THEN** the Enterprise card SHALL link to enterprise configuration, module signing, custom registries, and module security + +### Requirement: Nav items carry expertise data attribute +Each nav item rendered in the sidebar SHALL have a `data-expertise` HTML attribute containing the comma-separated expertise levels from `nav.yml`, enabling CSS-based filtering. + +#### Scenario: Nav item data attribute +- **WHEN** a nav item with `expertise: [beginner, intermediate]` is rendered +- **THEN** the `
  • ` element SHALL have `data-expertise="beginner,intermediate"` diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-theme-toggle/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-theme-toggle/spec.md new file mode 100644 index 0000000..ce3e79e --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/docs-theme-toggle/spec.md @@ -0,0 +1,49 @@ +## ADDED Requirements + +### Requirement: Dual CSS theme definitions +The stylesheet SHALL define CSS custom properties for both light and dark themes using `[data-theme="light"]` and `[data-theme="dark"]` selectors on the `` element. A `@media (prefers-color-scheme)` fallback SHALL apply when no explicit `data-theme` attribute is set. + +#### Scenario: Dark theme variables +- **WHEN** the `data-theme` attribute is set to `dark` +- **THEN** the site SHALL use a dark navy background (`#0a192f`), light text (`#ccd6f6`), and a subdued cyan accent (`#57e6c4`) + +#### Scenario: Light theme variables +- **WHEN** the `data-theme` attribute is set to `light` +- **THEN** the site SHALL use a white/off-white background, dark text, and a SpecFact teal accent (`#0d9488`) + +#### Scenario: System preference fallback +- **WHEN** no `data-theme` attribute is set on `` +- **THEN** the site SHALL use `@media (prefers-color-scheme: dark)` and `@media (prefers-color-scheme: light)` to match the user's OS preference + +### Requirement: Theme toggle button +A theme toggle button SHALL be rendered in the site header via `docs/_includes/theme-toggle.html`. The button SHALL display a sun icon in dark mode and a moon icon in light mode. + +#### Scenario: Toggle from dark to light +- **WHEN** the user clicks the theme toggle button while in dark mode +- **THEN** the site SHALL switch to light mode immediately and store `"light"` in `localStorage` under the key `specfact-theme` + +#### Scenario: Toggle from light to dark +- **WHEN** the user clicks the theme toggle button while in light mode +- **THEN** the site SHALL switch to dark mode immediately and store `"dark"` in `localStorage` + +### Requirement: Theme persistence prevents FOUC +A `theme.js` script SHALL be loaded in the `` element (before body renders) to read the stored theme from `localStorage` and set the `data-theme` attribute before any content is painted. + +#### Scenario: Returning visitor sees stored theme +- **WHEN** a user who previously selected light mode visits any page +- **THEN** the page SHALL render in light mode without any flash of dark mode + +### Requirement: Theme-aware Mermaid diagrams +Mermaid.js SHALL be re-initialized with appropriate `themeVariables` when the theme changes. Dark mode SHALL use the existing dark mermaid theme. Light mode SHALL use mermaid's `default` theme with SpecFact teal accents. + +#### Scenario: Mermaid diagrams update on toggle +- **WHEN** the user toggles from dark to light mode +- **THEN** all Mermaid diagrams on the page SHALL re-render with light-mode colors + +### Requirement: Theme-aware syntax highlighting +Rouge syntax highlighting token classes SHALL have color overrides for both light and dark themes so that code blocks are readable in both modes. + +#### Scenario: Code blocks readable in light mode +- **WHEN** the site is in light mode +- **THEN** code block backgrounds SHALL be light with dark syntax-highlighted text +- **AND** all token classes (keywords, strings, comments, etc.) SHALL have sufficient contrast against the light background diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md new file mode 100644 index 0000000..7536583 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/modules-docs-command-validation/spec.md @@ -0,0 +1,65 @@ +# Specs - Modules Docs Command Validation + +## MODIFIED Requirements + +### Requirement: Docs validation SHALL reject stale command and resource references + +The modules-side docs validation workflow SHALL reject command examples across published module docs that do not match implemented bundle commands and SHALL also reject stale references to migrated core-owned resource paths. + +#### Scenario: Valid command example passes + +- **GIVEN** a docs page references `specfact backlog ceremony standup` +- **WHEN** the validation runs +- **THEN** it finds a matching registration in the backlog package source +- **AND** the check passes + +#### Scenario: Published non-bundle docs are validated too + +- **GIVEN** a published module docs page outside `docs/bundles/` contains a command example +- **WHEN** the validation runs +- **THEN** the command example is checked against the implemented mounted command tree +- **AND** stale former command forms are rejected the same way as bundle reference pages + +#### Scenario: Invalid command example fails + +- **GIVEN** a docs page references `specfact backlog nonexistent` +- **WHEN** the validation runs +- **THEN** it reports the mismatch +- **AND** the check fails + +#### Scenario: Legacy core-owned resource path reference fails + +- **GIVEN** a docs page instructs users to fetch a migrated prompt or template from a legacy core-owned path +- **WHEN** the validation runs +- **THEN** it reports the stale resource reference +- **AND** the check fails + +### Requirement: Published module docs SHALL stay warning-free in docs review + +Published module docs SHALL include Jekyll front matter and valid internal links so the modules docs review run does not rely on warning allowlists for stale pages. + +#### Scenario: Previously tolerated stale docs warnings are removed + +- **GIVEN** a published modules docs page was previously missing front matter or linked to a removed former docs target +- **WHEN** the docs review suite runs +- **THEN** the page is published with required front matter +- **AND** its internal links resolve to current canonical modules docs routes +- **AND** the docs review run completes without warnings + +### Requirement: Nav data file link targets SHALL be validated + +The docs validation script SHALL verify that every URL in `_data/nav.yml` corresponds to an existing page with a matching permalink. + +#### Scenario: Nav link to non-existent page fails validation + +- **GIVEN** `_data/nav.yml` contains a link to `/bundles/spec/nonexistent/` +- **WHEN** the validation runs +- **THEN** it reports that no page exists with permalink `/bundles/spec/nonexistent/` +- **AND** the check fails + +#### Scenario: All nav links resolve to existing pages + +- **GIVEN** `_data/nav.yml` contains all current navigation links +- **WHEN** the validation runs +- **THEN** every URL in the nav file matches an existing page's permalink +- **AND** the check passes diff --git a/openspec/changes/docs-13-nav-search-theme-roles/specs/team-setup-docs/spec.md b/openspec/changes/docs-13-nav-search-theme-roles/specs/team-setup-docs/spec.md new file mode 100644 index 0000000..a1ec2a7 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/specs/team-setup-docs/spec.md @@ -0,0 +1,27 @@ +## MODIFIED Requirements + +### Requirement: Team setup docs SHALL cover operational onboarding and resource ownership + +Team setup guidance SHALL explain onboarding, shared configuration, role-based workflows, and how bundle-owned prompts/templates are rolled out and kept in sync. The sidebar Team & Enterprise section SHALL link to all team/enterprise pages at their correct `/team-and-enterprise/` paths. + +#### Scenario: Team setup guide covers onboarding + +- **GIVEN** the `team-collaboration` doc +- **WHEN** a team lead reads the page +- **THEN** it covers initial team setup, shared configuration, role-based workflows, and recommended collaboration patterns + +#### Scenario: Team docs explain bundle-owned resource rollout + +- **GIVEN** the team setup docs +- **WHEN** a team lead reads the page +- **THEN** the docs explain that prompts and bundle-specific workspace templates ship from installed bundles +- **AND** they describe how teams keep those resources aligned through supported bootstrap commands and version management + +#### Scenario: Sidebar Team & Enterprise links use correct paths + +- **WHEN** the Team & Enterprise section is rendered in the sidebar +- **THEN** it SHALL link to Team Collaboration at `/team-and-enterprise/team-collaboration/` +- **AND** Agile & Scrum Setup at `/team-and-enterprise/agile-scrum-setup/` +- **AND** Multi-Repo Setup at `/team-and-enterprise/multi-repo/` +- **AND** Enterprise Configuration at `/team-and-enterprise/enterprise-config/` +- **AND** no links SHALL point to stale paths like `/team-collaboration-workflow/` or `/guides/agile-scrum-workflows/` diff --git a/openspec/changes/docs-13-nav-search-theme-roles/tasks.md b/openspec/changes/docs-13-nav-search-theme-roles/tasks.md new file mode 100644 index 0000000..510ef06 --- /dev/null +++ b/openspec/changes/docs-13-nav-search-theme-roles/tasks.md @@ -0,0 +1,56 @@ +# docs-13 Tasks + +## 1. Data-Driven Navigation + +- [x] 1.1 Create `docs/_data/nav.yml` with all seven sections, correct bundle links (Overview + command pages for all 6 bundles), correct Team & Enterprise paths, and complete Workflows section +- [x] 1.2 Create `docs/_includes/sidebar-nav.html` Liquid partial that renders nav from `site.data.nav` with `
    ` for bundles, active-page highlighting via `page.url`, and `data-expertise` attributes on `
  • ` elements +- [x] 1.3 Update `docs/_layouts/default.html` to replace hardcoded sidebar nav with `{% include sidebar-nav.html %}` +- [x] 1.4 Fix `docs/index.md` homepage table: update Spec, Govern, Code Review, and Codebase deep-dive links to point to actual bundle command pages +- [x] 1.5 Add "Find Your Path" role-based entry cards section to `docs/index.md` with Solo Developer, Startup, Corporate, and Enterprise profiles + +## 2. Light/Dark Theme Toggle + +- [x] 2.1 Create `docs/assets/js/theme.js` — reads `localStorage` key `specfact-theme`, sets `data-theme` on ``, provides toggle function +- [x] 2.2 Create `docs/_includes/theme-toggle.html` — toggle button with sun/moon SVG icons +- [x] 2.3 Update `docs/_layouts/default.html` to load `theme.js` in `` and include theme toggle in header +- [x] 2.4 Refactor `docs/assets/main.scss` — replace single `:root` block with `[data-theme="dark"]` and `[data-theme="light"]` variable definitions; add `@media (prefers-color-scheme)` fallback +- [x] 2.5 Add light-mode Rouge syntax highlighting overrides to `main.scss` +- [x] 2.6 Refactor Mermaid initialization in `default.html` into theme-aware `initMermaid(theme)` function with separate `themeVariables` for light/dark + +## 3. Client-Side Search + +- [x] 3.1 Create `docs/assets/js/search-index.json` as Liquid template that generates JSON array from all pages with title, url, keywords, audience, expertise_level, and truncated content +- [x] 3.2 Create `docs/assets/js/search.js` — Lunr.js integration with lazy index loading, debounced input, field boosting (title:10, keywords:5, content:1), dropdown results with snippets and metadata pills +- [x] 3.3 Create `docs/_includes/search.html` — search input UI with placeholder and keyboard shortcut hint +- [x] 3.4 Update `docs/_layouts/default.html` to load Lunr.js CDN, include search partial in sidebar above nav, and load search.js + +## 4. Expertise Filter + +- [x] 4.1 Create `docs/_includes/expertise-filter.html` — compact dropdown with All/Beginner/Intermediate/Advanced options and visible-count indicator +- [x] 4.2 Create `docs/assets/js/filters.js` — reads `localStorage` key `specfact-expertise`, applies CSS filtering via `data-expertise` attributes, updates count indicator +- [x] 4.3 Update `docs/_layouts/default.html` to include expertise filter partial between search and nav, and load filters.js + +## 5. Front Matter Enrichment + +- [x] 5.1 Add `keywords`, `audience`, and `expertise_level` fields to all Getting Started pages (~7 files) +- [x] 5.2 Add front matter fields to all Bundle pages (~24 files across 6 bundles) +- [x] 5.3 Add front matter fields to all Workflow/Guide pages (~10 active workflow files) +- [x] 5.4 Add front matter fields to all Integration pages (~6 files) +- [x] 5.5 Add front matter fields to all Team & Enterprise pages (4 files) +- [x] 5.6 Add front matter fields to all Authoring pages (~7 files) +- [x] 5.7 Add front matter fields to all Reference pages (~14 files) + +## 6. Theme Refinement & Breadcrumbs + +- [x] 6.1 Create `docs/_includes/breadcrumbs.html` — derive breadcrumb trail from `page.url` segments +- [x] 6.2 Update `docs/_layouts/default.html` to include breadcrumbs above content area +- [x] 6.3 Refine `main.scss` — reduce sidebar visual weight, improve code block contrast with subtle left-border accent, cleaner `
    ` chevron animation, better table borders, search/filter/toggle styling for both themes + +## 7. Validation & CI + +- [x] 7.1 Extend `scripts/check-docs-commands.py` to validate all `_data/nav.yml` URL targets resolve to existing pages +- [x] 7.2 Verify Jekyll build succeeds locally with `cd docs && bundle exec jekyll build` +- [x] 7.3 Verify all sidebar links render correctly (no `/reference/commands/` placeholders remain) +- [x] 7.4 Verify light/dark toggle works and persists across page loads +- [x] 7.5 Verify search returns results for known keywords +- [x] 7.6 Verify expertise filter hides/shows nav items correctly diff --git a/scripts/check-docs-commands.py b/scripts/check-docs-commands.py index bd28798..a2a9c54 100644 --- a/scripts/check-docs-commands.py +++ b/scripts/check-docs-commands.py @@ -41,6 +41,7 @@ MARKDOWN_CODE_RE = re.compile(r"`([^`\n]*specfact [^`\n]*)`") MARKDOWN_LINK_RE = re.compile(r"(? None: def _iter_validation_docs_paths() -> list[Path]: - return sorted(path.resolve() for path in DOCS_ROOT.rglob("*.md")) + paths: list[Path] = [] + excluded_parts = {"_site", "vendor"} + for path in sorted(DOCS_ROOT.rglob("*.md")): + relative_parts = path.relative_to(DOCS_ROOT).parts + if any(part in excluded_parts for part in relative_parts): + continue + paths.append(path.resolve()) + return paths def _iter_bash_examples(text: str, source: Path) -> list[CommandExample]: @@ -132,6 +140,19 @@ def _load_docs_texts(paths: list[Path]) -> dict[Path, str]: return {path: path.read_text(encoding="utf-8") for path in paths} +def _extract_front_matter(text: str) -> dict[str, object]: + lines = text.splitlines() + if not lines or lines[0].strip() != YAML_FRONT_MATTER_DELIMITER: + return {} + + for index in range(1, len(lines)): + if lines[index].strip() != YAML_FRONT_MATTER_DELIMITER: + continue + data = yaml.safe_load("\n".join(lines[1:index])) or {} + return data if isinstance(data, dict) else {} + return {} + + def _normalize_command_text(command_text: str) -> list[str]: normalized = command_text.strip().rstrip(":.,") return normalized.split() @@ -270,6 +291,91 @@ def _validate_core_docs_config(config_path: Path) -> list[ValidationFinding]: return findings +def _normalize_docs_route(route: str) -> str | None: + normalized = route.strip() + if not normalized or normalized.startswith(("http://", "https://", "#")): + return None + if not normalized.startswith("/"): + normalized = f"/{normalized}" + if normalized != "/" and not normalized.endswith("/"): + normalized += "/" + return normalized + + +def _route_for_doc(path: Path, text: str) -> str: + front_matter = _extract_front_matter(text) + permalink = front_matter.get("permalink") + if isinstance(permalink, str): + normalized = _normalize_docs_route(permalink) + if normalized is not None: + return normalized + + relative_path = path.relative_to(DOCS_ROOT) + if relative_path.name == "index.md": + parent = relative_path.parent + return "/" if str(parent) == "." else f"/{'/'.join(parent.parts)}/" + if relative_path.name.lower() == "readme.md": + parent = relative_path.parent + return "/" if str(parent) == "." else f"/{'/'.join(parent.parts)}/" + path_no_ext = relative_path.with_suffix("") + if str(path_no_ext.parent) == ".": + return f"/{path_no_ext.name}/" if path_no_ext.name else "/" + return f"/{'/'.join(path_no_ext.parts)}/" + + +def _build_valid_docs_routes(text_by_path: dict[Path, str]) -> set[str]: + return {_route_for_doc(path, text) for path, text in text_by_path.items()} + + +def _iter_yaml_url_nodes(node: yaml.Node | None) -> list[tuple[str, int]]: + if node is None: + return [] + + found: list[tuple[str, int]] = [] + if isinstance(node, yaml.MappingNode): + for key_node, value_node in node.value: + if getattr(key_node, "value", None) == "url" and isinstance(value_node, yaml.ScalarNode): + found.append((value_node.value, value_node.start_mark.line + 1)) + found.extend(_iter_yaml_url_nodes(value_node)) + elif isinstance(node, yaml.SequenceNode): + for child in node.value: + found.extend(_iter_yaml_url_nodes(child)) + return found + + +def _validate_nav_data_links(nav_path: Path, valid_routes: set[str]) -> list[ValidationFinding]: + findings: list[ValidationFinding] = [] + raw_text = nav_path.read_text(encoding="utf-8") + try: + nav_node = yaml.compose(raw_text) + except yaml.YAMLError as exc: + line_number = 1 + if hasattr(exc, "problem_mark") and exc.problem_mark is not None: + line_number = exc.problem_mark.line + 1 + findings.append( + ValidationFinding( + category="nav-parse", + source=nav_path, + line_number=line_number, + message=f"Failed to parse navigation data: {exc}", + ) + ) + return findings + for raw_url, line_number in _iter_yaml_url_nodes(nav_node): + normalized = _normalize_docs_route(raw_url) + if normalized is None or normalized in valid_routes: + continue + findings.append( + ValidationFinding( + category="nav-link", + source=nav_path, + line_number=line_number, + message=f"Navigation URL does not resolve to an existing page: {raw_url}", + ) + ) + return findings + + def _format_findings(findings: list[ValidationFinding]) -> str: return "\n".join( f"{_script_name(finding.source)}:{finding.line_number}: [{finding.category}] {finding.message}" @@ -281,11 +387,13 @@ def _main() -> int: docs_paths = _iter_validation_docs_paths() text_by_path = _load_docs_texts(docs_paths) valid_paths = _build_valid_command_paths() + valid_routes = _build_valid_docs_routes(text_by_path) findings = [ *_validate_command_examples(text_by_path, valid_paths), *_validate_legacy_resource_paths(text_by_path), *_validate_core_docs_links(text_by_path), *_validate_core_docs_config(DOCS_ROOT / "_config.yml"), + *_validate_nav_data_links(DOCS_ROOT / "_data" / "nav.yml", valid_routes), ] if findings: sys.stdout.write(_format_findings(findings) + "\n")