CR-2026-03-25: Domus Digitalis AsciiDoc + Seed Implementation

Change Summary

Field Value

Change ID

CR-2026-03-25-DOMUS-DIGITALIS

Application

domus-digitalis (Project Management App)

Location

~/atelier/_projects/personal/domus-digitalis/

Status

COMPLETED

Implemented By

Claude Code

Date

2026-03-25

Risk Level

Low (additive changes, no breaking modifications)

Scope of Work

Two deliverables completed in this session:

  1. Seed Script - Idempotent project seeding from JSON

  2. AsciiDoc Workspace - Standalone editor in Visual Atelier

Deliverable 1: Seed Script

Problem

35 projects defined in projects.json needed to be loaded into PostgreSQL. Manual entry unacceptable.

Solution

Created prisma/seed.js with:

  • dotenv loading for DATABASE_URL

  • Slug generation from title

  • Upsert logic (create if new, update if exists)

  • Filter for valid project objects (skip comment-only entries)

Files Created

File Purpose

apps/backend/prisma/seed.js

Seed script (~125 lines)

apps/backend/prisma/seed-data/projects.json

35 projects with metadata (existed, populated earlier)

Key Code

require('dotenv').config();  // Critical - loads DATABASE_URL

const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

// Filter out pure comment entries (objects with only _comment, no title)
const projects = data.projects.filter(p => p.title);

// Upsert logic using slug as unique identifier
const existing = await prisma.projects.findUnique({ where: { slug } });
if (existing) {
  await prisma.projects.update({ where: { slug }, data: projectData });
} else {
  await prisma.projects.create({ data: { ...projectData, slug } });
}

Execution Result

🏠 Domus Digitalis Project Seeder
────────────────────────────────────────

🌱 Seeding 35 projects...

  ✅ Created: Cisco ISE 3.4 Upgrade
  ✅ Created: iPSK Manager HA Deployment
  ... (8 more created)
  ✏️  Updated: Vault SSH Certificate Authority
  ✏️  Updated: Network Automation CLI
  ... (23 more updated)

📊 Seed Summary:
   Created: 10
   Updated: 25
   Errors:  0
   Total:   35

✨ Seeding complete!

Issues Encountered and Fixed

Issue Cause Fix

DATABASE_URL not found

dotenv not loaded

Added require('dotenv').config(); at top

Only 25 of 35 projects processed

Filter !p._comment excluded projects WITH _comment annotations

Changed to p.title to include all objects with titles

Deliverable 2: AsciiDoc Workspace Editor

Problem

Visual Atelier workspace (/atelier/workspace) had Mermaid, PlantUML, Draw.io but no AsciiDoc. User preference is AsciiDoc for all documentation.

Solution

Added AsciiDoc as fourth editor in Visual Atelier with:

  • Live preview using asciidoctor.js

  • 14 example templates (organized in 4 categories)

  • Export to HTML and .adoc

  • Save/Load via useDiagramStorage hook

  • Fullscreen preview mode

  • Share functionality

Files Modified

File Action Changes

app/atelier/workspace/layout.tsx

Modified

Added "Document Tools" category with AsciiDoc entry

app/atelier/workspace/page.tsx

Modified

Changed grid from 3 to 4 columns, added AsciiDoc card

app/atelier/workspace/asciidoc/page.tsx

Created

Full standalone editor (~1170 lines, includes 14 example templates)

Layout Changes

// Added new category in tools array
{
  category: 'Document Tools',
  items: [
    {
      icon: '📝',
      name: 'AsciiDoc',
      desc: 'Technical documentation',
      route: '/atelier/workspace/asciidoc',
      status: 'ready'
    }
  ]
}

Editor Features

Feature Implementation

Live Preview

asciidoctor.js with dynamic import (client-side only)

Templates

14 templates in 4 categories (see below)

Export HTML

Blob download with rendered HTML

Export .adoc

Blob download with source

Save/Load

useDiagramStorage('asciidoc') hook

Fullscreen

Preview-only fullscreen mode

Share

URL token generation

Example Templates Included (14 total)

Basics:

  • (1) Basic Document - Headers, paragraphs, lists

  • (2) Tables - Column specs, alignment

  • (3) Code Blocks - Source highlighting, callouts

  • (4) Admonitions - NOTE, TIP, WARNING, IMPORTANT, CAUTION

Advanced:

  • (5) Advanced Tables - Colspan, rowspan, AsciiDoc content in cells, nested tables

  • (6) Definition Lists - Glossary style, horizontal definitions, Q&A format

  • (7) Blocks & Quotes - Sidebars, blockquotes, verse, example blocks, open blocks

  • (8) Attributes & Variables - Document attributes, conditionals, counters

Macros & Formatting:

  • (9) UI Macros - kbd, menu, btn macros, icons, text formatting

  • (10) Footnotes & Anchors - Inline/named footnotes, custom anchors, bibliography

  • (11) Checklists - Task lists, nested checklists, project status tables

  • (12) Passthrough & Raw - Raw HTML, literal blocks, stem/math notation

Templates:

  • (13) Includes & Refs - Partial and example includes, cross-references

  • (14) Runbook Template - Phase structure with validation steps

Bug Fix: White Window / Narrow Fullscreen

Initial implementation had rendering issues:

Issue Root Cause Fix

White window (no preview)

html state started empty; asciidoctor loaded async with no loading indicator

Added asciidoctorLoading state, loading spinner, immediate initial conversion on load

Narrow fullscreen

max-w-4xl constrained width to ~896px

Changed to w-full max-w-none for full-width rendering

Textarea fixed height

h-[500px] instead of filling panel

Changed to flex-1 with h-full to fill available space

TypeScript errors

convert() returns string | Document; saveDiagram expected undefined not null

Added as string cast; changed null to undefined

HTML generated but invisible

@tailwindcss/typography not installed; prose classes did nothing

Installed plugin, added to tailwind.config.js plugins array
Typography Plugin Installation
cd apps/frontend
npm install @tailwindcss/typography
tailwind.config.js
plugins: [
  require('@tailwindcss/typography'),
],

Verification

Seed Script

cd ~/atelier/_projects/personal/domus-digitalis/apps/backend
npm run db:seed

Expected: 35 projects, 0 errors

AsciiDoc Workspace

  1. Navigate to localhost:3000/atelier/workspace

  2. Click AsciiDoc card (or use sidebar)

  3. Select template from Examples dropdown

  4. Verify live preview renders correctly

  5. Test Export HTML and Export .adoc

  6. Test Save, refresh page, verify Load works

Documentation Updates

File Changes

projects/personal/domus-digitalis/index.adoc

Created comprehensive project documentation with full stack enumeration

projects/index.adoc

Added Domus Digitalis to Personal Projects table

Sign-Off

Role Name Date

Requestor

Evan Rosado

2026-03-25

Implementer

Claude Code

2026-03-25

Status

COMPLETED

2026-03-25