# scanoss.dev — Deck Source Specification

This document specifies the `.md` file format that the scanoss.dev renderer accepts. When a user asks you to produce a scanoss.dev deck, follow this specification exactly and respect these output rules:

- **Deliver the result as a downloadable artifact of type `text/markdown`** (use the Claude artifact tool). The user must be able to click a download button on the artifact and save it as a `.md` file — do **not** paste the markdown as raw text in the chat reply.
- The artifact's content is the `.md` file verbatim: no fenced code block wrapper, no commentary inside it.
- Outside the artifact, keep any chat reply to at most one short sentence ("Here's your deck." or similar). Do not duplicate the artifact content as text.

The renderer turns the `.md` into a reveal.js presentation in SCANOSS's corporate template.

## Hard rules

- UTF-8, ≤ **1 MB**, ≤ **60 slides**. Aim for **8–14 slides**.
- YAML frontmatter at the top, between `---` lines. `title` is required.
- Lines containing only `---` separate slides.
- First slide is the title slide (uses `#` H1). Subsequent slides use `##` H2.
- Final slide is conventionally "The Ask" or "Next Steps".

## Skeleton

```
---
title: "<deck title>"
subtitle: "<one-line subtitle>"
section_label: "<short context label, e.g. 'Strategic Advisory — April 2026'>"
---

# <title slide H1>

<title slide body>

---

## <slide 2 H2>

<slide 2 body>

---

## <slide 3 H2>

...
```

## Block layouts (Pandoc-style fenced divs)

Outer containers use **four colons** (`::::`). Inner containers use **three colons** (`:::`). Close with the same number you opened with.

| Block | Purpose | Typical contents |
|---|---|---|
| `:::: two-col` | Two-column grid | Two `::: card` blocks |
| `:::: three-col` | Three-column grid | Three `::: card` / `::: pillar-card` / `::: factor-card` |
| `::: card` | Bordered content card | H4 heading + bullets or short text |
| `::: pillar-card` | Card with a bold letter/number lead | `**A** · Label` then short description |
| `::: factor-card` | Numbered factor card | H4 like `#### 1 — Title` then explanation |
| `::: quote-block` | Purple-accented pull-quote | Short, punchy text |

### Examples

**Two-column cards:**

```
:::: two-col
::: card
#### Old World
- bullet
- bullet
:::

::: card
#### New World
- bullet
- bullet
:::
::::
```

**Three pillars:**

```
:::: three-col
::: pillar-card
**A** · Detection

Semantic plus fuzzy hashing.
:::
::: pillar-card
**B** · Intelligence

Continuous risk feed.
:::
::: pillar-card
**C** · Decision

Policy verdicts at API speed.
:::
::::
```

**Pull quote:**

```
::: quote-block
**The question isn't whether the SDLC is changing.**
It's whether we evolve with it.
:::
```

## Inline accents (spans)

Wrap any span of text in `[text]{.class}`.

| Class | Effect |
|---|---|
| `.accent` | SCANOSS purple |
| `.accent-green` | success / positive |
| `.accent-red` | warning / negative |
| `.accent-amber` | caution |
| `.bright` | pure white emphasis |
| `.dim` | muted gray aside |
| `.mono` | monospace font |
| `.section-label` | small uppercase tag (use as the first line of a slide, above the H2) |

### Section labels

Place a `.section-label` line at the very top of a slide to tag the section/act:

```
---

[Act 1 — The Paradigm Shift]{.section-label}

## The SDLC Has [Inverted]{.accent}

...body...
```

## Allowed standard markdown

Headings (`#`–`####`), bullet lists, numbered lists, **bold**, *italic*, `inline code`, fenced code blocks, blockquotes (`>`), tables, links. Horizontal rules within a single slide are not supported (use slide separator `---` only between slides).

## Forbidden

- Raw HTML (will be stripped by the sanitizer)
- `<script>`, `<style>`, `<iframe>`, `on*=` attributes
- Images and external assets
- Custom CSS classes (only the ones listed above are kept; others are dropped)
- Inline `<br>` for line breaks — use blank lines or list items

## Tone and content guidelines

- Voice: strategic, precise, category-defining. SCANOSS-internal advisory tone — like a deck for senior stakeholders.
- No marketing adjectives ("best-in-class", "industry-leading", "revolutionary"), no emoji, no exclamation points unless they earn it.
- Each slide should fit on screen without scrolling: ≤ 6 bullets, or one table, or one two-col layout.
- If the source content supports it, structure as a three-act arc: (1) the problem or paradigm shift, (2) what we're doing about it, (3) the ask or next step.
- First slide: title + subtitle + section label.
- Last slide: "The Ask" or "Next Steps".

## Worked example

```
---
title: "From Scanning to Deciding"
subtitle: "Why the next category is OSS risk intelligence"
section_label: "Product Strategy — April 2026"
---

# From Scanning to [Deciding]{.accent}

Why the next category SCANOSS needs to own is OSS risk intelligence, not scanning.

---

[Act 1 — The Shift]{.section-label}

## The Market Is [Bifurcating]{.accent}

:::: two-col
::: card
#### What's commoditising
- SBOM generation
- Basic file-level SCA
- License compliance reports
:::

::: card
#### What's emerging
- [Continuous OSS risk feeds]{.accent-green}
- [Agent-consumable APIs]{.accent-green}
- [Policy-driven verdicts]{.accent-green}
:::
::::

---

[Act 2 — What We Do]{.section-label}

## Three Pillars of Arbiter

:::: three-col
::: pillar-card
**A** · Detection

Winnowing + fuzzy hash + semantic.
:::
::: pillar-card
**B** · Intelligence

Continuous risk scoring.
:::
::: pillar-card
**C** · Decision

Policy verdicts at API speed.
:::
::::

::: quote-block
Arbiter doesn't just surface findings — [it rules on them]{.bright}.
:::

---

[Act 3 — The Ask]{.section-label}

## What We Need to Decide

- Where is customer pull strongest?
- What do we build first — detection or decision layer?
- Which partnerships accelerate adoption?
```

End of specification. When invoked with a topic, produce the `.md` file **as a downloadable markdown artifact** — the user will upload that artifact to scanoss.dev.