Skip to content

Commit 2980eec

Browse files
angelovstantonangelovstanton
committed
034: move USAGE & CUSTOMIZATION guides to docs/ as docs-site pages
These two guides were embedded resources buried under src/Spectra.CLI/Skills/Content/Docs/, invisible on the docs site even though they're top-tier user documentation. Move them to docs/ so they ship with the GitHub Pages site and become discoverable. Changes: - git mv src/Spectra.CLI/Skills/Content/Docs/USAGE.md docs/usage.md - git mv src/Spectra.CLI/Skills/Content/Docs/CUSTOMIZATION.md docs/customization.md - Add Just the Docs frontmatter (parent: User Guide, nav_order 9 & 10) - Spectra.CLI.csproj: embed from ..\..\docs\*.md with explicit LogicalName so the runtime resource id stays 'Spectra.CLI.Skills.Content.Docs.USAGE.md' and ProfileFormatLoader needs no path changes - ProfileFormatLoader.LoadEmbeddedUsageGuide / LoadEmbeddedCustomizationGuide now strip leading YAML frontmatter before returning, so the files written to user project roots by spectra init / update-skills stay frontmatter-free - README docs table gets the two new entries 1453 tests still passing.
1 parent a6a7e68 commit 2980eec

File tree

5 files changed

+64
-7
lines changed

5 files changed

+64
-7
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,8 @@ SPECTRA is part of the [Automate The Planet](https://www.automatetheplanet.com/)
208208
| [Grounding Verification](docs/grounding-verification.md) | Dual-model critic for hallucination detection |
209209
| [Document Index](docs/document-index.md) | Pre-built doc index for efficient generation |
210210
| [Skills Integration](docs/skills-integration.md) | Copilot Chat SKILLs and agent prompts |
211+
| [Usage (Copilot Chat)](docs/usage.md) | Workflow-by-workflow guide for driving SPECTRA via Copilot Chat |
212+
| [Customization](docs/customization.md) | Every customization knob — config, profiles, prompts, palettes |
211213
| [Execution Agent](docs/execution-agent/overview.md) | MCP tools and AI-driven test execution |
212214
| [Architecture](docs/architecture/overview.md) | System design and key decisions |
213215
| [Development Guide](docs/DEVELOPMENT.md) | Building, testing, and running locally |

src/Spectra.CLI/Skills/Content/Docs/CUSTOMIZATION.md renamed to docs/customization.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: Customization
3+
parent: User Guide
4+
nav_order: 10
5+
---
6+
17
# SPECTRA Customization Guide
28

39
This guide covers every way you can customize SPECTRA's behavior, from test

src/Spectra.CLI/Skills/Content/Docs/USAGE.md renamed to docs/usage.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
---
2+
title: Usage (Copilot Chat)
3+
parent: User Guide
4+
nav_order: 9
5+
---
6+
17
# SPECTRA Usage Guide — VS Code Copilot Chat
28

39
This guide shows how to use SPECTRA through VS Code Copilot Chat. Every workflow below shows what to say and what to expect. For configuration and customization details, see `CUSTOMIZATION.md`.

‎src/Spectra.CLI/Profile/ProfileFormatLoader.cs‎

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,21 +55,55 @@ public static string LoadEmbeddedDefaultYaml()
5555
}
5656

5757
/// <summary>
58-
/// Returns the raw bytes of the embedded <c>CUSTOMIZATION.md</c>,
59-
/// for use by <c>spectra init</c> and <c>spectra update-skills</c>.
58+
/// Returns the embedded <c>CUSTOMIZATION.md</c> with any Jekyll YAML
59+
/// frontmatter stripped (the source file lives in <c>docs/</c> and carries
60+
/// frontmatter for the docs site, but user projects shouldn't see it).
6061
/// </summary>
6162
public static string LoadEmbeddedCustomizationGuide()
6263
{
63-
return ReadEmbeddedResource(EmbeddedCustomizationResource);
64+
return StripFrontmatter(ReadEmbeddedResource(EmbeddedCustomizationResource));
6465
}
6566

6667
/// <summary>
67-
/// Returns the raw bytes of the embedded <c>USAGE.md</c>,
68-
/// for use by <c>spectra init</c> and <c>spectra update-skills</c>.
68+
/// Returns the embedded <c>USAGE.md</c> with any Jekyll YAML frontmatter
69+
/// stripped. See <see cref="LoadEmbeddedCustomizationGuide"/> for the why.
6970
/// </summary>
7071
public static string LoadEmbeddedUsageGuide()
7172
{
72-
return ReadEmbeddedResource(EmbeddedUsageResource);
73+
return StripFrontmatter(ReadEmbeddedResource(EmbeddedUsageResource));
74+
}
75+
76+
/// <summary>
77+
/// Removes a leading Jekyll YAML frontmatter block (delimited by <c>---</c>
78+
/// on its own line at the very top, terminated by another <c>---</c> line)
79+
/// if present. Returns the input unchanged if no frontmatter is detected.
80+
/// </summary>
81+
private static string StripFrontmatter(string content)
82+
{
83+
if (string.IsNullOrEmpty(content)) return content;
84+
85+
// Detect a leading "---\n" or "---\r\n" delimiter.
86+
ReadOnlySpan<char> span = content.AsSpan();
87+
if (!span.StartsWith("---\n".AsSpan()) && !span.StartsWith("---\r\n".AsSpan()))
88+
{
89+
return content;
90+
}
91+
92+
// Find the closing "---" delimiter on its own line.
93+
const string closing = "\n---";
94+
var closingIdx = content.IndexOf(closing, 3, StringComparison.Ordinal);
95+
if (closingIdx < 0) return content;
96+
97+
// Skip past the closing "---" and the trailing newline (if any).
98+
var bodyStart = closingIdx + closing.Length;
99+
if (bodyStart < content.Length && content[bodyStart] == '\r') bodyStart++;
100+
if (bodyStart < content.Length && content[bodyStart] == '\n') bodyStart++;
101+
102+
// Skip a single blank line if it follows the frontmatter.
103+
if (bodyStart < content.Length && content[bodyStart] == '\r') bodyStart++;
104+
if (bodyStart < content.Length && content[bodyStart] == '\n') bodyStart++;
105+
106+
return content.Substring(bodyStart);
73107
}
74108

75109
private static string LoadEmbeddedFormat()

‎src/Spectra.CLI/Spectra.CLI.csproj‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,16 @@
3939
<EmbeddedResource Include="Skills\Content\Skills\*.md" />
4040
<EmbeddedResource Include="Skills\Content\Agents\*.md" />
4141
<EmbeddedResource Include="Skills\Content\Profiles\*.yaml" />
42-
<EmbeddedResource Include="Skills\Content\Docs\*.md" />
42+
<!-- Customization & Usage guides live in the top-level docs/ folder
43+
(so they ship with the docs site) but are still embedded here
44+
under the original logical names so ProfileFormatLoader can read
45+
them with no code changes. -->
46+
<EmbeddedResource Include="..\..\docs\customization.md" Link="Skills\Content\Docs\CUSTOMIZATION.md">
47+
<LogicalName>Spectra.CLI.Skills.Content.Docs.CUSTOMIZATION.md</LogicalName>
48+
</EmbeddedResource>
49+
<EmbeddedResource Include="..\..\docs\usage.md" Link="Skills\Content\Docs\USAGE.md">
50+
<LogicalName>Spectra.CLI.Skills.Content.Docs.USAGE.md</LogicalName>
51+
</EmbeddedResource>
4352
<EmbeddedResource Include="Prompts\Content\*.md" />
4453
<EmbeddedResource Include="Templates\deploy-dashboard.yml" />
4554
<EmbeddedResource Include="Dashboard\Templates\index.html" />

0 commit comments

Comments
 (0)
⚡