npm - @arjunkhera/atlas - Versions diffs - 0.3.15 → 0.3.17 - Mend

@arjunkhera/atlas 0.3.15 → 0.3.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/.claude-plugin/plugin.json +1 -1
package/agents/artifact-format/example.html +23 -7
package/agents/artifact-format/system.css +71 -18
package/agents/artifact-renderer.md +42 -11
package/door/cli.mjs +12 -3
package/door/lib/design.mjs +50 -1
package/package.json +1 -1
package/skills/lead/SKILL.md +1 -1
package/skills/sdlc-task/SKILL.md +4 -3
package/skills/sdlc-task/design/README.md +11 -1
package/skills/sdlc-task/templates/design-hub.html +1 -1

package/.claude-plugin/plugin.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/agents/artifact-format/example.html CHANGED Viewed

@@ -1,21 +1,24 @@
-<!-- The structural reference for a rendered design doc. Neutral content: a
+<!-- The structural reference for a rendered page. Neutral content: a
      made-up repo, "orders-api". Copy the structure and the classes, never the
-     words. In a real render, paste system.css where the comment says. -->
+     words. In a real render, paste system.css where the comment says. Every
+     colour below is a token from system.css, so the page works in the light
+     and the dark theme. Never write a colour value here. -->
 <title>Refund rounding</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Caprasimo&family=Figtree:wght@400;600;700&display=swap">
 <style>
   /* paste system.css here in a real render */
-  body { background: #fcfbf9; color: #211d19; font: 16.5px/1.7 Figtree, system-ui, sans-serif; margin: 0; }
+  body { background: var(--color-bg); color: var(--color-text); font: 16.5px/1.7 Figtree, system-ui, sans-serif; margin: 0; }
   [data-shell] { display: grid; grid-template-columns: 288px minmax(0, 860px); gap: 40px; padding-inline: 24px; }
   [data-rail] { position: sticky; top: 0; align-self: start; padding-block: 28px; display: flex; flex-direction: column; gap: 14px; }
   [data-main] { padding-block: 28px 80px; }
   h1, h2 { font-family: Caprasimo, Georgia, serif; font-weight: 400; text-wrap: balance; }
   h2 { font-size: 29px; margin: 0; }
-  .kicker { font-size: 11px; letter-spacing: .14em; text-transform: uppercase; color: #a97f5f; font-weight: 700; }
-  .intent { font-style: italic; color: #5c554e; margin: 4px 0 12px; }
-  .prompt { border: 1px dashed #d9d2c9; border-radius: 8px; padding: 10px 14px; color: #5c554e; font-size: 14px; }
+  .kicker { font-size: 11px; letter-spacing: .14em; text-transform: uppercase; color: var(--color-accent); font-weight: 700; }
+  .intent { font-style: italic; color: var(--color-muted); margin: 4px 0 12px; }
+  .prompt { border: 1px dashed var(--color-line-strong); border-radius: 8px; padding: 10px 14px; color: var(--color-muted); font-size: 14px; }
   .table-wrap { overflow-x: auto; }
-  section { padding-block: 28px; border-bottom: 1px solid #ece7e1; }
+  section { padding-block: 28px; border-bottom: 1px solid var(--color-line); }
+  .theme { font: inherit; font-size: 13px; color: var(--color-text); background: var(--color-surface); border: 1px solid var(--color-line-strong); border-radius: 999px; padding: 4px 12px; cursor: pointer; align-self: start; }
   @media (max-width: 760px) { [data-shell] { grid-template-columns: 1fr; padding-inline: 16px; } [data-rail] { position: static; } }
 </style>
 <div data-shell>
@@ -23,6 +26,7 @@
     <div class="kicker">orders-api · Design doc</div>
     <div style="font-family: Caprasimo, Georgia, serif; font-size: 22px; line-height: 1.1">Refund rounding</div>
     <div><span class="tag tag-accent">DRAFT</span> <span class="tag tag-neutral">service</span></div>
+    <button type="button" class="theme" id="theme" hidden>Dark</button>
     <nav style="display: flex; flex-direction: column; gap: 4px; font-size: 14px">
       <strong>1 · Frame</strong>
       <a href="#summary">Summary</a>
@@ -69,3 +73,15 @@
     </section>
   </main>
 </div>
+<script>
+  // Optional. With no script the page follows the system setting. The switch
+  // sets data-theme on <html>, and system.css lets that choice win.
+  (function () {
+    var root = document.documentElement, btn = document.getElementById('theme');
+    var dark = false;
+    try { dark = window.matchMedia('(prefers-color-scheme: dark)').matches; } catch (e) {}
+    function show() { btn.textContent = dark ? 'Light' : 'Dark'; }
+    btn.hidden = false; show();
+    btn.addEventListener('click', function () { dark = !dark; root.setAttribute('data-theme', dark ? 'dark' : 'light'); show(); });
+  })();
+</script>

package/agents/artifact-format/system.css CHANGED Viewed

@@ -1,22 +1,5 @@
 /* Organic — design-system tokens and component classes. This file is the source of truth for the system's look; retune it here and see readme.md. */
 :root {
   --color-bg: #f5ead8;
   --color-surface: #ebddc5;
@@ -77,6 +60,76 @@
   --shadow-sm: 0 1px 2px color-mix(in srgb, #2e2b25 14%, transparent);
   --shadow-md: 0 3px 10px color-mix(in srgb, #2e2b25 16%, transparent);
   --shadow-lg: 0 12px 32px color-mix(in srgb, #2e2b25 22%, transparent);
+  --color-scrim: color-mix(in srgb, #2e2b25 50%, transparent);
+}
+/* The quiet reading palette, light and dark (owner, 9 October 2026: "We
+   should support a dark mode as well"). The light set is the ratified quiet
+   override of the Organic ground. The dark set holds the same names, so a
+   page that uses only tokens works in both themes. The page follows the
+   system setting. A switch can set data-theme="light" or "dark" on <html>,
+   and that choice wins. Never write a colour on a page outside these blocks. */
+:root {
+  --color-bg: #fcfbf9;
+  --color-surface: #f4f0ea;
+  --color-text: #211d19;
+  --color-muted: #5c554e;
+  --color-line: #ece7e1;
+  --color-line-strong: #d9d2c9;
+  --color-accent: #a97f5f;
+  color-scheme: light;
+}
+:root[data-theme="dark"] {
+  --color-bg: #1d1b19;
+  --color-surface: #282522;
+  --color-text: #ece6dd;
+  --color-muted: #b5ada2;
+  --color-line: #36322e;
+  --color-line-strong: #4d4842;
+  --color-accent: #d3a27c;
+  --color-accent-2: #a9ba88;
+  --color-divider: color-mix(in srgb, #ece6dd 16%, transparent);
+  --color-neutral-100: #2e2b25; --color-neutral-200: #3a362f; --color-neutral-300: #474238;
+  --color-neutral-400: #645c50; --color-neutral-500: #82796a; --color-neutral-600: #a19786;
+  --color-neutral-700: #c0b6a5; --color-neutral-800: #dcd3c4; --color-neutral-900: #f2ece2;
+  --color-accent-100: #402310; --color-accent-200: #643312; --color-accent-300: #8c491a;
+  --color-accent-400: #b2622d; --color-accent-500: #d67f48; --color-accent-600: #f6a06b;
+  --color-accent-700: #ffc6a5; --color-accent-800: #ffe1d0; --color-accent-900: #fff2eb;
+  --color-accent-2-100: #272e1b; --color-accent-2-200: #3d472b; --color-accent-2-300: #56633f;
+  --color-accent-2-400: #728157; --color-accent-2-500: #8fa073; --color-accent-2-600: #aebf92;
+  --color-accent-2-700: #ccdbb2; --color-accent-2-800: #e1eecc; --color-accent-2-900: #f0fae1;
+  --shadow-sm: 0 0 0 1px color-mix(in srgb, #ece6dd 8%, transparent);
+  --shadow-md: 0 0 0 1px color-mix(in srgb, #ece6dd 10%, transparent), 0 4px 12px color-mix(in srgb, #000000 40%, transparent);
+  --shadow-lg: 0 0 0 1px color-mix(in srgb, #ece6dd 12%, transparent), 0 12px 32px color-mix(in srgb, #000000 55%, transparent);
+  --color-scrim: color-mix(in srgb, #000000 60%, transparent);
+  color-scheme: dark;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --color-bg: #1d1b19;
+    --color-surface: #282522;
+    --color-text: #ece6dd;
+    --color-muted: #b5ada2;
+    --color-line: #36322e;
+    --color-line-strong: #4d4842;
+    --color-accent: #d3a27c;
+    --color-accent-2: #a9ba88;
+    --color-divider: color-mix(in srgb, #ece6dd 16%, transparent);
+    --color-neutral-100: #2e2b25; --color-neutral-200: #3a362f; --color-neutral-300: #474238;
+    --color-neutral-400: #645c50; --color-neutral-500: #82796a; --color-neutral-600: #a19786;
+    --color-neutral-700: #c0b6a5; --color-neutral-800: #dcd3c4; --color-neutral-900: #f2ece2;
+    --color-accent-100: #402310; --color-accent-200: #643312; --color-accent-300: #8c491a;
+    --color-accent-400: #b2622d; --color-accent-500: #d67f48; --color-accent-600: #f6a06b;
+    --color-accent-700: #ffc6a5; --color-accent-800: #ffe1d0; --color-accent-900: #fff2eb;
+    --color-accent-2-100: #272e1b; --color-accent-2-200: #3d472b; --color-accent-2-300: #56633f;
+    --color-accent-2-400: #728157; --color-accent-2-500: #8fa073; --color-accent-2-600: #aebf92;
+    --color-accent-2-700: #ccdbb2; --color-accent-2-800: #e1eecc; --color-accent-2-900: #f0fae1;
+    --shadow-sm: 0 0 0 1px color-mix(in srgb, #ece6dd 8%, transparent);
+    --shadow-md: 0 0 0 1px color-mix(in srgb, #ece6dd 10%, transparent), 0 4px 12px color-mix(in srgb, #000000 40%, transparent);
+    --shadow-lg: 0 0 0 1px color-mix(in srgb, #ece6dd 12%, transparent), 0 12px 32px color-mix(in srgb, #000000 55%, transparent);
+    --color-scrim: color-mix(in srgb, #000000 60%, transparent);
+    color-scheme: dark;
+  }
 }
 body {
@@ -252,7 +305,7 @@ textarea.input { min-height: 90px; resize: vertical; }
 .dialog-backdrop {
   position: fixed; inset: 0; display: grid; place-items: center;
   padding: var(--space-4);
-  background: color-mix(in srgb, var(--color-neutral-900) 50%, transparent);
+  background: var(--color-scrim);
 }
 .dialog {
   width: min(440px, 100%); display: flex; flex-direction: column; gap: var(--space-3);

package/agents/artifact-renderer.md CHANGED Viewed

@@ -2,12 +2,12 @@
 name: artifact-renderer
 description: >
   Dedicated Sonnet subagent that renders a design doc, PRD, review, or task explainer into
-  the owner-ratified HTML artifact treatment (one light theme in the
-  Claude-website family), or draws one custom figure for a design part, written for a smart newcomer ("assume like a fresher"), diagram-rich,
+  the owner-ratified HTML artifact treatment (the quiet Organic format, with a
+  light and a dark theme from one token set), or draws one custom figure for a design part, written for a smart newcomer ("assume like a fresher"), diagram-rich,
   with every stable id backlinked to its definition. Invoked by the sdlc-task design loop and
   any session presenting a design/task/review to the owner — rendering is mechanical work and
-  runs on Sonnet (sdlc-task skill, "Model tiering"). Input: a repo markdown doc path (+ optional emphasis
-  notes). Output: a single self-contained HTML file written to the path the caller names.
+  runs on Sonnet (sdlc-task skill, "Model tiering"). Input: a repo markdown doc path (+ optional caller
+  notes, limited to the list in the file). Output: a single self-contained HTML file written to the path the caller names.
   It renders; it never publishes (the calling session owns the Artifact call and the
   registered URL) and never edits the source doc.
 model: sonnet
@@ -21,7 +21,7 @@ reader treatment. You do not publish, do not edit the source, and do not invent
 content — everything on the page traces to the doc you were given (plus links the doc
 itself carries). Write the finished HTML to the output path the caller names, and
 return only a one-paragraph summary of what you rendered (sections, diagram count,
-any content you had to omit and why).
+any content you had to omit and why), and the "Refused notes:" line.
 ## Designs: figures only. Every other doc: an Organic page
@@ -47,9 +47,37 @@ are in `${CLAUDE_PLUGIN_ROOT}/skills/sdlc-task/design/README.md`, under
 **Every other doc** (an older design, a PRD, a review, a task explainer)
 renders in the Organic page format below.
+## Caller notes: what you follow and what you refuse
+A caller can add notes to the doc path. The format is the owner's, not the
+caller's. Follow a note only when it is in this list:
+1. Which sections to stress, or which to put first in reading order.
+2. Which terms to explain at more length for a newcomer.
+3. Which companion docs to read to explain a reference.
+4. Which flow or sequence to draw, and which one to animate.
+5. The output path.
+6. Whether the page goes to anyone other than the owner. Then you also run
+   the share check, below.
+Refuse every other note. A note that changes the format is refused. Some
+examples:
+- a new box or banner, such as "What I need from you" above the summary;
+- a colour, a font, a theme, or one theme only;
+- a change to the shell, the rail, the section list or the section anatomy;
+- a remote host, a library or a script that the page needs to show content;
+- content that the source doc does not hold.
+Render the page without the refused note. In your summary, add a line
+"Refused notes:" that names each refused note and the rule it breaks. If no
+note was refused, write "Refused notes: none". The calling session tells the
+owner. A change to the format is a change to this file, and the owner decides
+it.
 ## The ratified treatment (the owner's format — do not drift)
-**THE RATIFIED FORMAT is the "Organic" quiet-light design-doc format**, from an
+**THE RATIFIED FORMAT is the "Organic" quiet reading format**, from an
 exemplar the owner supplied, with the words *"we need to ensure our future
 agents create artefacts like these"*. Its assets ship with this crew — read
 them, do not restyle from prose:
@@ -64,11 +92,14 @@ them, do not restyle from prose:
 Apply, per the ratification:
-- **Quiet reading palette override** on the Organic tokens: near-white warm
-  ground `#fcfbf9`, one warm-grey ramp, muted clay accent `#a97f5f`. **One light
-  scheme only.** Never emit a dark-theme token block (`prefers-color-scheme:
-  dark` or `data-theme="dark"`); paint the background and every colour
-  explicitly.
+- **Two themes from one token set.** `system.css` holds the quiet reading
+  palette in a light set and a dark set with the same names. The owner asked
+  for dark mode on 9 October 2026. Paste the whole sheet, its dark blocks too.
+  Paint every colour with a token, such as `var(--color-bg)`,
+  `var(--color-text)`, `var(--color-muted)` or `var(--color-accent)`.
+  Never write a colour value outside the sheet's token blocks.
+- **The page follows the system setting.** A light or dark switch, as in
+  `example.html`, is optional. The page must work with its script removed.
 - **Shell**: 288px sticky left rail — kicker "<repo name> · Design doc", title,
   status tags, per-section completeness meter, TOC grouped 1·Frame /
   2·Requirements / 3·Current state / 4·Design / 5·Decisions / 6·Delivery /

package/door/cli.mjs CHANGED Viewed

@@ -23,7 +23,7 @@ import { scan, toText, verdict, CHECK_VERSION, SPECS } from '../shape/check.mjs'
 import { packagePackageVersion } from './lib/releases.mjs';
 import { install, upgrade, doctor } from './lib/install.mjs';
 import { checkPaths, LIMITS } from './lib/ste.mjs';
-import { checkDesignFolder } from './lib/design.mjs';
+import { checkDesignFolder, designFolderOf, repoRootFrom } from './lib/design.mjs';
 import { writeDesignPage, readTracker } from './lib/design-build.mjs';
 import { loadPrivateTerms } from './lib/privacy.mjs';
 import { checkCommand as testsCheck, writeCommand as testsWrite } from './lib/tests.mjs';
@@ -52,6 +52,8 @@ const HELP = `atlas — the door into a repo's Atlas files
       --share                          also run the privacy filter, quotes included
       --terms <file>                   private terms; default ~/.config/atlas/private-terms.txt
   atlas design check <folder> …        check a design folder: each needed part, no state line, every code in the Key
+  atlas design folder                  print where this repo keeps its designs: design.folder in atlas.yaml, or docs/design-docs
+      --root <repo>                    the repo; default the nearest folder up from here that holds atlas.yaml
   atlas design build <folder>          build the design's page from its folder
       --tracker <file>                 the tracker data, as JSON, from the lead
       --out <file>                     the page; default docs/artifacts/<folder name>.html
@@ -117,7 +119,7 @@ export const FLAGS = Object.freeze({
   'kind-drift': { root: 'optional', 'record-kind': 'value', registry: 'value', repo: 'value' },
   check: { root: 'optional', repo: 'value', 'fail-on': 'value' },
   ste: { share: 'switch', terms: 'value' },
-  design: { tracker: 'value', out: 'value', draft: 'switch' },
+  design: { tracker: 'value', out: 'value', draft: 'switch', root: 'optional' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -258,7 +260,14 @@ function steCommand(chosen) {
 function designCommand(chosen) {
   const what = chosen._[1];
   const folders = chosen._.slice(2);
-  if (what !== 'check' && what !== 'build') throw new Error('use atlas design check <folder> or atlas design build <folder>');
+  if (what === 'folder') {
+    if (folders.length || chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft) throw new Error('atlas design folder takes only --root.');
+    const where = designFolderOf(chosen.root === undefined || chosen.root === true ? repoRootFrom(process.cwd()) : resolve(chosen.root));
+    line(where.folder);
+    return 0;
+  }
+  if (chosen.root !== undefined) throw new Error('--root works only with atlas design folder.');
+  if (what !== 'check' && what !== 'build') throw new Error('use atlas design check <folder>, atlas design build <folder> or atlas design folder');
   if (!folders.length) throw new Error(`give a design folder: atlas design ${what} <folder>`);
   if (what === 'check' && (chosen.tracker !== undefined || chosen.out !== undefined || chosen.draft)) throw new Error('--tracker, --out and --draft work only with atlas design build.');
   if (what === 'build') {

package/door/lib/design.mjs CHANGED Viewed

@@ -10,7 +10,7 @@
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseYaml } from '../../shape/check.mjs';
+import { parseYaml, insideRepo } from '../../shape/check.mjs';
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const PARTS_FILE = join(PACKAGE_ROOT, 'skills', 'sdlc-task', 'design', 'parts.yaml');
@@ -227,3 +227,52 @@ export function checkDesign(design, registry = loadRegistry()) {
 export function checkDesignFolder(folder, registry) {
   return checkDesign(readDesign(folder), registry);
 }
+// Where a repo keeps its designs. A repo sets the folder in atlas.yaml, as
+// `design: { folder: docs/design }`. Without the key, the folder is
+// docs/design-docs, so a repo that never sets it does not change. The shape
+// check does not read the key: a check change makes every repo's copy behind.
+// The path is relative to the repo root, plain (no `.`, `..` or `~`), and
+// never in a folder that a tool owns or a crew may not read.
+export const DEFAULT_DESIGN_FOLDER = 'docs/design-docs';
+export const CLOSED_FOLDERS = Object.freeze(['.git', '.github', '.claude', '.atlas', 'node_modules']);
+export function designFolderOf(root) {
+  const fallback = { folder: DEFAULT_DESIGN_FOLDER, path: join(root, DEFAULT_DESIGN_FOLDER), from: 'default' };
+  const facts = join(root, 'atlas.yaml');
+  const data = existsSync(facts) ? parseYaml(readFileSync(facts, 'utf8')) : null;
+  if (!data || typeof data !== 'object' || !Object.hasOwn(data, 'design')) return fallback;
+  const design = data.design;
+  if (!design || typeof design !== 'object' || Array.isArray(design)) throw new Error('atlas.yaml: design must be a map with one key, such as "design: { folder: docs/design }". Remove design to keep docs/design-docs.');
+  const unknown = Object.keys(design).filter((key) => key !== 'folder');
+  if (unknown.length) throw new Error(`atlas.yaml: design has the unknown key(s) ${unknown.join(', ')}. The one key is folder.`);
+  const raw = design.folder;
+  if (typeof raw !== 'string' || !raw.trim()) throw new Error('atlas.yaml: design.folder must be a path, such as docs/design.');
+  const steps = raw.trim().replace(/\/+$/, '').split('/');
+  if (raw.trim().startsWith('/') || /^[A-Za-z]:/.test(raw.trim()) || steps.some((step) => step === '' || step === '.' || step === '..' || step.includes('\\')) || steps[0].startsWith('~')) {
+    throw new Error(`atlas.yaml: design.folder "${raw}" must be a plain path inside the repo, relative to its root, such as docs/design.`);
+  }
+  if (CLOSED_FOLDERS.includes(steps[0])) throw new Error(`atlas.yaml: design.folder "${raw}" is in ${steps[0]}/, which a tool owns or a crew may not read. Pick a folder such as docs/design.`);
+  const folder = steps.join('/');
+  return { folder, path: join(root, folder), from: 'atlas.yaml' };
+}
+// The repo root for a command run with no --root: the nearest folder, from
+// here up, that holds atlas.yaml. The search stops at the git root. With no
+// atlas.yaml on the way, it is the folder the command ran in.
+export function repoRootFrom(start) {
+  for (let dir = resolve(start); ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'atlas.yaml'))) return dir;
+    if (existsSync(join(dir, '.git')) || dirname(dir) === dir) return resolve(start);
+  }
+}
+// Each design in the repo: a folder under the design folder that holds
+// design.yaml. A missing design folder holds no designs.
+export function designFoldersIn(root) {
+  const { path } = designFolderOf(root);
+  if (!existsSync(path) || !statSync(path).isDirectory()) return [];
+  return readdirSync(path, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(path, entry.name, DESIGN_FILE)))
+    .map((entry) => join(path, entry.name));
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md CHANGED Viewed

@@ -101,7 +101,7 @@ set. A test keeps the two lists equal.
 | `atlas code-read` | To resolve the citations of a code digest |
 | `atlas ste` | Before each publish; `--share` before a page goes to anyone else |
 | `atlas tests` | `write` puts the test kit in an area. `check` runs before a merge. `proof` prints the proof table of one run |
-| `atlas design` | `check` before you show a design; `build` to make its page |
+| `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 A person merges every file that `atlas tooling` writes.
 A person merges every file that `atlas tests write` writes.

package/skills/sdlc-task/SKILL.md CHANGED Viewed

@@ -68,8 +68,9 @@ with hashes retire.)
    commit to it. Local sessions use `feature/`, `fix/` or `chore/`; cloud
    sessions use `claude/`. The pull request targets that branch.
 4. **Design** (standard and above): follow [`design/README.md`](design/README.md).
-   Pick the kinds, and say why. Make the folder `docs/design-docs/<slug>/`
-   with `design.yaml`, then write the Summary, Your words and Goals first.
+   Pick the kinds, and say why. Make the folder `<design folder>/<slug>/`
+   with `design.yaml` (`atlas design folder` prints the design folder),
+   then write the Summary, Your words and Goals first.
    Read the template for each part in `design/parts/`. List the folder in
    `docs/index.md` in the commit that first lands it. Hotfix tier skips the design: the definition of done lives on
    the work item, and a resume anchor covers pauses.
@@ -123,7 +124,7 @@ A lock is the owner's approval of a short design (target design, flow 4).
    not.
 4. Call `item_lock` with the definition of done as `scope.text`. Set
    `scope.design_doc` to a link to the design at the approved commit, such
-   as `https://github.com/<owner>/<repo>/tree/<sha>/docs/design-docs/<slug>`.
+   as `https://github.com/<owner>/<repo>/tree/<sha>/<design folder>/<slug>`.
    The verb keeps a fingerprint of that text for
    the tools. No person reads or writes a hash, and no frozen text is copied
    into the doc.

package/skills/sdlc-task/design/README.md CHANGED Viewed

@@ -126,8 +126,18 @@ change as work moves went to the tracker.
 ## The folder
+Each design is one folder in the repo's design folder. `atlas design folder`
+prints that folder. A repo sets it in `atlas.yaml`:
+```yaml
+design:
+  folder: docs/design
+```
+Without the key, the design folder is `docs/design-docs`.
 ```text
-docs/design-docs/<slug>/
+<design folder>/<slug>/
   design.yaml      title, item, product, kinds, shared, look
   summary.md       ---
                    part: summary

package/skills/sdlc-task/templates/design-hub.html CHANGED Viewed

@@ -37,7 +37,7 @@ a { color: var(--accent); }
 <div class="wrap"><table>
 <thead><tr><th>Changed</th><th>Product</th><th>Design</th><th>State</th><th>Source</th></tr></thead>
 <tbody>
-<tr><td class="when">2026-10-07</td><td class="product">atlas</td><td><a href="https://claude.ai/artifact/EXAMPLE">Design docs as walkthroughs, in one place</a></td><td><span class="state build">Building</span></td><td><a href="https://github.com/ACCOUNT/REPO/blob/master/docs/design-docs/EXAMPLE.md">design doc</a></td></tr>
+<tr><td class="when">2026-10-07</td><td class="product">atlas</td><td><a href="https://claude.ai/artifact/EXAMPLE">Design docs as walkthroughs, in one place</a></td><td><span class="state build">Building</span></td><td><a href="https://github.com/ACCOUNT/REPO/tree/master/DESIGN-FOLDER/EXAMPLE">design doc</a></td></tr>
 </tbody>
 </table></div>
 </main></body></html>