uniweb 0.8.31 → 0.8.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.31",
+  "version": "0.8.33",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,11 +42,11 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/core": "0.5.18",
-    "@uniweb/kit": "0.7.20",
-    "@uniweb/runtime": "0.6.26"
+    "@uniweb/kit": "0.7.21",
+    "@uniweb/runtime": "0.6.28"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.8.30",
+    "@uniweb/build": "0.8.32",
     "@uniweb/content-reader": "1.1.4",
     "@uniweb/semantic-parser": "1.1.8"
   },

package/partials/agents.md

@@ -398,7 +398,7 @@ function Hello() {
 
 Access: `content.snippets[0]` → `{ language: 'jsx', code: 'function Hello() {...}' }`. The `language` attribute is a display hint for syntax highlighting, not a parsing format. Filter by language: `content.snippets.filter(s => s.language === 'css')`.
 
-Both appear in `content.sequence` for document-order rendering. The difference: tagged data blocks are parsed and extracted to `content.data`; code snippets are preserved and collected in `content.snippets`.
+Both appear in `content.sequence` for document-order rendering. The difference: tagged data blocks are parsed and extracted to `content.data`; code snippets are preserved and collected in `content.snippets`. `<Prose>` handles this automatically — it renders code snippets with syntax highlighting and skips tagged data blocks, which components access separately via `content.data`.
 
 ### Composition: Nesting and Embedding
 
@@ -875,12 +875,29 @@ Kit provides `H1` through `H6` — use the appropriate level for semantic hierar
 **Full content rendering** (article/docs sections where the author controls the flow):
 
 ```jsx
-import { Section, Article } from '@uniweb/kit'
+import { Section, Prose } from '@uniweb/kit'
 
 <Section block={block} width="lg" padding="md" />
-<Article block={block} />
+<Prose content={content} block={block} />
 ```
 
+`Prose` renders from the parsed content sequence — headings, paragraphs, images, code snippets, lists, etc. — with prose typography. Tagged data blocks are **skipped** (they're structured data, not prose). Access them via `content.data` for custom rendering:
+
+```jsx
+function Lesson({ content, block }) {
+  return (
+    <div>
+      <Prose content={content} block={block} />
+      {content.data.quiz && <Quiz data={content.data.quiz} />}
+    </div>
+  )
+}
+```
+
+Pass `content` (the parsed content object — has `.sequence`). Pass `block` too if the content uses insets. Also works as a pure typography wrapper: `<Prose>{children}</Prose>`.
+
+`Article` is an older alternative that renders from `block.rawContent` (raw ProseMirror nodes) — it renders everything including data blocks. Prefer `Prose` for new components.
+
 **Visuals:**
 
 ```jsx
@@ -893,7 +910,7 @@ import { Visual } from '@uniweb/kit'
 
 **Rendering text:** `H1`–`H6`, `P`, `Span`, `Div`, `Text` (with `as` prop)
 
-**Rendering content:** `Section` (full section with prose + layout), `Article` (prose content from `block.rawContent`), `Render` (ProseMirror nodes → React), `ChildBlocks` (render child sections)
+**Rendering content:** `Section` (full section with prose + layout), `Prose` (prose from parsed content sequence, skips data blocks), `Article` (raw ProseMirror rendering), `Render` (ProseMirror nodes → React), `ChildBlocks` (render child sections)
 
 **Rendering media:** `Visual` (first non-empty: inset/video/image), `Image`, `Media`, `Icon`
 

package/src/commands/doctor.js

@@ -5,6 +5,8 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join, resolve, basename, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
+import { getCliVersion } from '../versions.js'
+import { readAgentsVersion } from '../utils/agents-stamp.js'
 
 // ANSI colors
 const colors = {
@@ -484,6 +486,29 @@ export async function doctor(args = []) {
     }
   }
 
+  // Check AGENTS.md freshness
+  log('')
+  const agentsPath = join(workspaceDir, 'AGENTS.md')
+  const agentsVersion = readAgentsVersion(agentsPath)
+  const cliVersion = getCliVersion()
+
+  if (!existsSync(agentsPath)) {
+    warn('AGENTS.md not found')
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: 'AGENTS.md not found' })
+  } else if (!agentsVersion) {
+    // No stamp — manually created or pre-stamp version
+    warn('AGENTS.md has no version stamp (may be outdated)')
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: 'AGENTS.md has no version stamp' })
+  } else if (agentsVersion !== cliVersion) {
+    warn(`AGENTS.md is outdated (v${agentsVersion} → v${cliVersion})`)
+    info(`Run: uniweb update`)
+    issues.push({ type: 'warn', message: `AGENTS.md outdated (v${agentsVersion} → v${cliVersion})` })
+  } else {
+    success(`AGENTS.md is up to date (v${cliVersion})`)
+  }
+
   // Summary
   log('')
   log('─'.repeat(50))

package/src/commands/update.js

@@ -0,0 +1,55 @@
+/**
+ * uniweb update - Update generated project files
+ *
+ * Regenerates AGENTS.md from the installed CLI version.
+ */
+
+import { existsSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+import { readAgentsVersion, generateAgentsContent } from '../utils/agents-stamp.js'
+import { getCliVersion } from '../versions.js'
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m'
+}
+
+const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
+const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
+const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
+const log = console.log
+
+export async function update(args = []) {
+  const workspaceDir = findWorkspaceRoot(process.cwd())
+
+  if (!workspaceDir) {
+    error('Not in a Uniweb workspace')
+    log(`${colors.dim}Run this command from your project root or a package directory.${colors.reset}`)
+    process.exit(1)
+  }
+
+  const cliVersion = getCliVersion()
+  const agentsPath = join(workspaceDir, 'AGENTS.md')
+  const currentVersion = readAgentsVersion(agentsPath)
+
+  if (currentVersion === cliVersion) {
+    success(`AGENTS.md is already up to date (v${cliVersion})`)
+    return
+  }
+
+  const content = generateAgentsContent()
+  writeFileSync(agentsPath, content)
+
+  if (currentVersion) {
+    success(`Updated AGENTS.md (v${currentVersion} → v${cliVersion})`)
+  } else {
+    success(`Created AGENTS.md (v${cliVersion})`)
+  }
+}

package/src/index.js

@@ -35,6 +35,7 @@ import { publish } from './commands/publish.js'
 import { deploy } from './commands/deploy.js'
 import { invite } from './commands/invite.js'
 import { handoff } from './commands/handoff.js'
+import { update } from './commands/update.js'
 import { template } from './commands/template.js'
 import {
   resolveTemplate,
@@ -479,6 +480,12 @@ async function main() {
     return
   }
 
+  // Handle update command
+  if (command === 'update') {
+    await update(args.slice(1))
+    return
+  }
+
   // Handle inspect command
   if (command === 'inspect') {
     await inspect(args.slice(1))
@@ -794,6 +801,7 @@ ${colors.bright}Commands:${colors.reset}
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation
   doctor             Diagnose project configuration issues
+  update             Update AGENTS.md to match installed CLI version
   i18n <cmd>         Internationalization (extract, sync, status)
   template publish   Publish a site as a cloud template
   login              Log in to your Uniweb account

package/src/utils/agents-stamp.js

@@ -0,0 +1,41 @@
+/**
+ * AGENTS.md version stamp utilities
+ *
+ * The stamp is an HTML comment on the first line: <!-- uniweb-agents v0.8.32 -->
+ * Used by `doctor` (freshness check) and `update` (regeneration).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { getCliVersion } from '../versions.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+const STAMP_PATTERN = /^<!-- uniweb-agents v([\d.]+) -->/
+
+/**
+ * Read the version stamp from an AGENTS.md file
+ * @param {string} filePath - Absolute path to AGENTS.md
+ * @returns {string|null} Version string or null if no stamp
+ */
+export function readAgentsVersion(filePath) {
+  if (!existsSync(filePath)) return null
+  try {
+    const firstLine = readFileSync(filePath, 'utf8').split('\n')[0]
+    const match = firstLine.match(STAMP_PATTERN)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Generate AGENTS.md content with version stamp
+ * @returns {string} Full AGENTS.md content with stamp
+ */
+export function generateAgentsContent() {
+  const partialsDir = join(__dirname, '..', '..', 'partials')
+  const agentsContent = readFileSync(join(partialsDir, 'agents.md'), 'utf8')
+  return `<!-- uniweb-agents v${getCliVersion()} -->\n${agentsContent}\n`
+}

package/src/utils/scaffold.js

@@ -11,7 +11,7 @@ import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import yaml from 'js-yaml'
 import { copyTemplateDirectory, registerVersions } from '../templates/processor.js'
-import { getVersionsForTemplates } from '../versions.js'
+import { getVersionsForTemplates, getCliVersion } from '../versions.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates')
@@ -36,6 +36,9 @@ export async function scaffoldWorkspace(targetDir, context, options = {}) {
   // because an empty packages: [] makes pnpm search parent directories.
   const skip = context.workspaceGlobs?.length ? [] : ['pnpm-workspace.yaml']
 
+  // Inject CLI version for AGENTS.md stamp
+  context = { ...context, cliVersion: getCliVersion() }
+
   const templatePath = join(TEMPLATES_DIR, 'workspace')
   await copyTemplateDirectory(templatePath, targetDir, context, {
     onProgress: options.onProgress,

package/src/versions.js

@@ -22,6 +22,15 @@ function getCliPackageJson() {
   return JSON.parse(readFileSync(packagePath, 'utf8'))
 }
 
+/**
+ * Get the CLI's own version
+ *
+ * @returns {string} CLI version (e.g., "0.8.32")
+ */
+export function getCliVersion() {
+  return getCliPackageJson().version
+}
+
 /**
  * Extract version number from version spec (e.g., "^0.1.4" -> "0.1.4")
  */

package/templates/workspace/AGENTS.md.hbs

@@ -1 +1,2 @@
+<!-- uniweb-agents v{{cliVersion}} -->
 {{> agents}}