fix: OCX registry compatibility and profile support (#67)

* fix: OCX registry compatibility and profile support

- Fix CI workflow to copy registry output to docs site root (index.json
  at /systematic/index.json, not /systematic/registry/index.json)
- Fix build script: include author field, strip v prefix from git tags,
  add files:[] for bundle/plugin packuments, remove version from
  component entries and packument version data
- Normalize target paths in build output (agents/ → agent/, commands/ →
  command/) to match OCX's required singular directory names while
  keeping plural in source
- Add profile components (standalone, omo) to registry with validation
- Fix .well-known/ocx.json registry path
- Update README and OCX guide with verified commands and profile docs
- Remove structural integrity tests (registry.test.ts)

* fix: harden registry build validation

- Refactor validateRegistry() to reduce cognitive complexity
- Resolve author from package.json when missing in registry source
- Harden git tag parsing to require semver or v-prefixed semver
- Add functional build-registry tests (validation, version errors,
  target path normalization)

Author: marcusrbrown

.github/workflows/docs.yaml

@@ -46,7 +46,7 @@ jobs:
         run: bun run --cwd docs build
 
       - name: Copy registry to docs output
-        run: cp -r dist/registry docs/dist/registry
+        run: cp -r dist/registry/. docs/dist/
 
       - name: Create GitHub App token
         if: github.repository == 'marcusrbrown/systematic'

README.md

@@ -84,7 +84,8 @@ ocx add systematic/skills     # All 11 skills
 ocx add systematic/agents     # All 24 agents
 ocx add systematic/commands   # All 9 commands
 
-# Or use a profile
+# Or use a profile (requires --global registry)
+ocx registry add https://fro.bot/systematic --name systematic --global
 ocx profile add sys --from systematic/standalone
 ```
 

docs/public/.well-known/ocx.json

@@ -1,4 +1,4 @@
 {
   "version": 1,
-  "registry": "/systematic/registry/index.json"
+  "registry": "/systematic/index.json"
 }

docs/src/content/docs/guides/ocx-registry.mdx

@@ -18,7 +18,7 @@ To use the Systematic registry with OCX, first add the registry to your local co
 ocx registry add https://fro.bot/systematic --name systematic
 ```
 
-The registry discovery file is located at `https://fro.bot/systematic/.well-known/ocx.json`.
+OCX resolves the registry automatically from the URL.
 
 ## Installing Components
 
@@ -76,6 +76,14 @@ ocx add systematic/commands
 
 Profiles provide a complete, "opinionated" configuration for Systematic. They can be installed as standalone projects or merged into existing ones.
 
+:::caution
+Profile installation requires the registry to be configured **globally** (not just in the project). Add the `--global` flag when adding the registry:
+
+```bash
+ocx registry add https://fro.bot/systematic --name systematic --global
+```
+:::
+
 ### Standalone Profile
 The `standalone` profile provides a minimal Systematic setup with only the `@fro.bot/systematic` plugin and all bundled assets.
 
@@ -165,8 +173,10 @@ If you have the npm plugin installed AND have added OCX components, Systematic w
 
 ### Profile not working
 If a profile installation fails or doesn't seem to apply:
-1. Verify the profile exists: `ocx profile list`
-2. Check your `OCX_PROFILE` environment variable if you are using profile switching.
+1. Verify the registry is configured **globally**: `ocx registry list --global`
+2. If missing, add it: `ocx registry add https://fro.bot/systematic --name systematic --global`
+3. Check existing profiles: `ocx profile list`
+4. If the profile already exists, remove it first: `ocx profile rm <name>`
 
 ### Missing skills after OCX install
 Individual skills installed via OCX do not automatically get "bootstrap injection" (the automatic loading of `using-systematic`). To get this feature, you must have the `@fro.bot/systematic` plugin installed in your project or globally.
@@ -176,6 +186,5 @@ If `ocx diff` shows differences but `ocx update` says you are up to date, the re
 
 ## Technical Details
 
-- **Registry URL:** `https://fro.bot/systematic/registry/`
-- **Discovery Path:** `/.well-known/ocx.json`
+- **Registry URL:** `https://fro.bot/systematic`
 - **Compatibility:** Systematic components are compatible with OpenCode 0.12.0 and later.

registry/registry.jsonc

@@ -743,6 +743,48 @@
       ],
       "files": []
     },
+    {
+      "name": "standalone",
+      "type": "ocx:profile",
+      "description": "Standalone Systematic profile — structured engineering workflows with zero extra configuration",
+      "files": [
+        {
+          "path": "profiles/standalone/opencode.jsonc",
+          "target": "opencode.jsonc"
+        },
+        {
+          "path": "profiles/standalone/ocx.jsonc",
+          "target": "ocx.jsonc"
+        },
+        {
+          "path": "profiles/standalone/AGENTS.md",
+          "target": "AGENTS.md"
+        }
+      ]
+    },
+    {
+      "name": "omo",
+      "type": "ocx:profile",
+      "description": "OhMyOpenCode (OMO) profile — Systematic with enhanced orchestration and delegation",
+      "files": [
+        {
+          "path": "profiles/omo/opencode.jsonc",
+          "target": "opencode.jsonc"
+        },
+        {
+          "path": "profiles/omo/ocx.jsonc",
+          "target": "ocx.jsonc"
+        },
+        {
+          "path": "profiles/omo/oh-my-opencode.jsonc",
+          "target": "oh-my-opencode.jsonc"
+        },
+        {
+          "path": "profiles/omo/AGENTS.md",
+          "target": "AGENTS.md"
+        }
+      ]
+    },
     {
       "name": "plugin",
       "type": "ocx:plugin",

scripts/build-registry.ts

@@ -58,7 +58,6 @@ interface PackumentFile {
 interface PackumentVersion {
   name: string
   type: string
-  version: string
   description?: string
   files?: PackumentFile[]
   dependencies?: string[]
@@ -74,14 +73,14 @@ interface Packument {
 interface IndexComponent {
   name: string
   type: string
-  version: string
   description?: string
 }
 
 interface RegistryIndex {
   name: string
   namespace: string
   version: string
+  author: string
   components: IndexComponent[]
 }
 
@@ -127,7 +126,14 @@ function resolveVersion(explicit: string | null): string {
       cwd: PROJECT_ROOT,
     }).trim()
     if (tag.length > 0) {
-      return tag
+      const normalized = tag.startsWith('v') ? tag.slice(1) : tag
+      if (SEMVER_REGEX.test(normalized)) {
+        return normalized
+      }
+      console.error(
+        `Error: Invalid git tag format "${tag}". Expected semver or v-prefixed semver (e.g., v1.2.3)`,
+      )
+      process.exit(1)
     }
   } catch {
     // git tag failed, fall through to package.json
@@ -190,33 +196,45 @@ function resolveComponentFilePath(
     return path.join(PROJECT_ROOT, file.path)
   }
 
+  if (type === 'ocx:profile') {
+    return path.join(PROJECT_ROOT, 'registry/files', file.path)
+  }
+
   return path.join(PROJECT_ROOT, 'registry/files', file.path)
 }
 
 function validateRegistry(source: RegistrySource): string[] {
   const errors: string[] = []
   const componentNames = new Set<string>()
 
+  const validators: Record<
+    string,
+    (component: RegistryComponent, errors: string[]) => void
+  > = {
+    'ocx:skill': validateSkillComponent,
+    'ocx:agent': validateFileComponent,
+    'ocx:command': validateFileComponent,
+    'ocx:bundle': (component, currentErrors) =>
+      validateBundleComponent(component, source, currentErrors),
+    'ocx:profile': validateProfileComponent,
+    'ocx:plugin': () => undefined,
+  }
+
   for (const component of source.components) {
     if (componentNames.has(component.name)) {
       errors.push(`Duplicate component name: "${component.name}"`)
     }
     componentNames.add(component.name)
 
-    if (component.type === 'ocx:skill') {
-      validateSkillComponent(component, errors)
-    } else if (component.type === 'ocx:agent') {
-      validateFileComponent(component, errors)
-    } else if (component.type === 'ocx:command') {
-      validateFileComponent(component, errors)
-    } else if (component.type === 'ocx:bundle') {
-      validateBundleComponent(component, source, errors)
-    } else if (component.type === 'ocx:plugin') {
-    } else {
+    const validator = validators[component.type]
+    if (validator == null) {
       errors.push(
         `[${component.name}] Unknown component type: "${component.type}"`,
       )
+      continue
     }
+
+    validator(component, errors)
   }
 
   return errors
@@ -286,6 +304,27 @@ function validateFileComponent(
   }
 }
 
+function validateProfileComponent(
+  component: RegistryComponent,
+  errors: string[],
+): void {
+  const prefix = `[${component.name}]`
+
+  if (!Array.isArray(component.files) || component.files.length === 0) {
+    errors.push(`${prefix} Profile component must have at least one file`)
+    return
+  }
+
+  for (const file of component.files) {
+    const diskPath = resolveComponentFilePath(component, file)
+    if (!fs.existsSync(diskPath)) {
+      errors.push(
+        `${prefix} File not found: ${file.path} (expected at ${diskPath})`,
+      )
+    }
+  }
+}
+
 function validateBundleComponent(
   component: RegistryComponent,
   source: RegistrySource,
@@ -329,6 +368,21 @@ function walkFiles(dir: string): string[] {
   return results
 }
 
+/** OCX requires singular directory names for agent/command targets */
+const OCX_TARGET_REWRITES: ReadonlyArray<[RegExp, string]> = [
+  [/^\.opencode\/agents\//, '.opencode/agent/'],
+  [/^\.opencode\/commands\//, '.opencode/command/'],
+]
+
+function normalizeTargetPath(target: string): string {
+  for (const [pattern, replacement] of OCX_TARGET_REWRITES) {
+    if (pattern.test(target)) {
+      return target.replace(pattern, replacement)
+    }
+  }
+  return target
+}
+
 /** SHA-256 integrity: sha256-{base64(digest)} per OCX spec */
 function computeIntegrity(content: Buffer): string {
   const hash = createHash('sha256').update(content).digest('base64')
@@ -347,7 +401,6 @@ function buildRegistry(source: RegistrySource, version: string): void {
     const entry: IndexComponent = {
       name: component.name,
       type: component.type,
-      version,
     }
     if (component.description != null) {
       entry.description = component.description
@@ -367,6 +420,7 @@ function buildRegistry(source: RegistrySource, version: string): void {
     name: source.name,
     namespace: source.namespace,
     version,
+    author: resolveAuthor(source),
     components: indexComponents,
   }
 
@@ -392,7 +446,7 @@ function buildPackument(component: RegistryComponent, version: string): void {
 
     packumentFiles.push({
       path: file.path,
-      target: file.target,
+      target: normalizeTargetPath(file.target),
       integrity,
     })
 
@@ -409,7 +463,6 @@ function buildPackument(component: RegistryComponent, version: string): void {
   const versionData: PackumentVersion = {
     name: component.name,
     type: component.type,
-    version,
   }
   if (component.description != null) {
     versionData.description = component.description
@@ -428,18 +481,37 @@ function buildPackument(component: RegistryComponent, version: string): void {
   )
 }
 
+function resolveAuthor(source: RegistrySource): string {
+  if (source.author != null && source.author.trim().length > 0) {
+    return source.author
+  }
+
+  const pkgPath = path.join(PROJECT_ROOT, 'package.json')
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as {
+      author?: string
+    }
+    const author = pkg.author
+    if (typeof author === 'string' && author.trim().length > 0) {
+      return author
+    }
+  } catch {}
+
+  return ''
+}
+
 function buildBundlePackument(
   component: RegistryComponent,
   version: string,
 ): void {
   const versionData: PackumentVersion = {
     name: component.name,
     type: component.type,
-    version,
   }
   if (component.description != null) {
     versionData.description = component.description
   }
+  versionData.files = []
   if (Array.isArray(component.dependencies)) {
     versionData.dependencies = component.dependencies
   }
@@ -463,11 +535,11 @@ function buildPluginPackument(
   const versionData: PackumentVersion = {
     name: component.name,
     type: component.type,
-    version,
   }
   if (component.description != null) {
     versionData.description = component.description
   }
+  versionData.files = []
   if (component.opencode != null) {
     versionData.opencode = component.opencode
   }