@morphist/aspects 0.1.2 → 0.1.4

package/README.md

@@ -7,22 +7,22 @@
   ╚═╝  ╚═╝╚══════╝╚═╝     ╚══════╝ ╚═════╝   ╚═╝   ╚══════╝
 ```
 
-> **Community Aspects Registry** — Personality modules for AI agents.
+> **The Open Aspect Registry** - Personality modules for AI agents.
 
-[![Validate PRs](https://github.com/aimorphist/aspects/actions/workflows/validate-pr.yml/badge.svg)](https://github.com/aimorphist/aspects/actions/workflows/validate-pr.yml)
+**Website:** [aspects.sh](https://aspects.sh) | **Docs:** [aspects.sh/docs](https://aspects.sh/docs)
 
 ---
 
 ## What are Aspects?
 
-Aspects are personality modules for AI agents. They define how an AI speaks, thinks, and behaves — from quirky wizards to helpful assistants to domain experts.
+Aspects are personality modules for AI agents. They define how an AI speaks, thinks, and behaves - from quirky wizards to helpful assistants to domain experts.
 
 Each aspect is a JSON file containing:
 
-- **Identity** — Name, tagline, character description
-- **Voice Hints** — Speaking speed, emotional tone, style guidance
-- **Modes** — Different behavioral modes (e.g., "campaign mode" for a D&D wizard)
-- **Prompt** — The core personality prompt
+- **Identity** - Name, tagline, character description
+- **Voice Hints** - Speaking speed, emotional tone, style guidance
+- **Modes** - Different behavioral modes (e.g., "campaign mode" for a D&D wizard)
+- **Prompt** - The core personality prompt
 
 ## Quick Start
 
@@ -58,7 +58,75 @@ npx @morphist/aspects add alaric
 npx @morphist/aspects add -g alaric
 ```
 
-See [CLI Documentation](./docs/CLI.md) for full reference.
+### Install Formats
+
+Multiple ways to specify an aspect:
+
+```bash
+# By name (registry)
+aspects add alaric
+
+# Anonymous aspect (name with hash suffix)
+aspects add my-wizard-7kYx3abc12
+
+# By URL
+aspects add https://aspects.sh/aspects/my-wizard-7kYx3abc12
+
+# By hash
+aspects add blake3:BnCcPam...
+
+# From GitHub
+aspects add github:user/repo
+
+# From local path
+aspects add ./path/to/aspect
+```
+
+### Create & Share (No Account Needed)
+
+The simplest way to publish an aspect:
+
+```bash
+# 1. Create your aspect interactively
+npx @morphist/aspects create my-aspect
+
+# 2. Edit the generated aspect.json (customize prompt, add directives)
+
+# 3. Share to the public registry
+npx @morphist/aspects share ./my-aspect
+# Output: ✓ Shared! Name: my-aspect-7kYx3abc12
+
+# 4. Anyone can now install it:
+npx @morphist/aspects add my-aspect-7kYx3abc12
+```
+
+### Publishing to Registry
+
+Two ways to publish aspects to the public registry:
+
+| Method | Command | Account | Features |
+|--------|---------|---------|----------|
+| **Share** | `aspects share` | No | Quick anonymous sharing via content hash |
+| **Publish** | `aspects publish` | Yes | Claim names, version updates, edit metadata |
+
+```bash
+# Anonymous sharing (no account)
+npx @morphist/aspects share ./my-aspect
+# Output: ✓ Shared! Name: my-aspect-7kYx3abc12
+#         Install with: npx @morphist/aspects add my-aspect-7kYx3abc12
+
+# Publishing with account
+npx @morphist/aspects login      # Create account or authenticate
+npx @morphist/aspects publish    # Claim name, publish versions
+```
+
+We fully embrace anonymous contributions - but creating an account lets you claim names and publish updates.
+
+### Behavioral Rules
+
+Aspects support **directives** (strict MUST-follow rules) and **instructions** (softer guidance). See [Instructions & Directives](#instructions--directives) for details.
+
+Run `npx @morphist/aspects --help` for quick reference, or see [CLI Documentation](./docs/CLI.md) for full details.
 
 ## Registry Structure
 
@@ -119,7 +187,9 @@ Aspects are defined in `aspect.json`:
 
 ### Categories
 
-Every aspect must have exactly one official category:
+Every aspect has exactly one category. You can use an official category or create your own custom category.
+
+**Official Categories:**
 
 | Category       | Description                        |
 | -------------- | ---------------------------------- |
@@ -132,6 +202,10 @@ Every aspect must have exactly one official category:
 | `spiritual`    | Mindfulness, wisdom, guidance      |
 | `pundit`       | Commentary, analysis, opinions     |
 
+**Custom Categories:**
+
+You can use any category name (2-20 characters, alphanumeric + hyphens, any case). Examples: `YOLO`, `my-niche`, `Cooking`.
+
 ### Optional Fields
 
 | Field        | Description                                |
@@ -146,106 +220,122 @@ Every aspect must have exactly one official category:
 
 ### Field Limits
 
-To prevent abuse, fields have maximum lengths:
-
-| Field         | Limit                   |
-| ------------- | ----------------------- |
-| `name`        | 50 characters           |
-| `displayName` | 100 characters          |
-| `tagline`     | 200 characters          |
-| `tags`        | 10 items, 30 chars each |
-| `prompt`      | 50,000 characters       |
-| `modes`       | 10 maximum              |
-
-## Create & Submit an Aspect
-
-### Fork & Pull Request
-
-The standard way to contribute:
-
-1. **Fork this repository** on GitHub
-
-2. **Clone your fork**
-
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/aspects
-   cd aspects
-   ```
-
-3. **Create your aspect** (use the CLI or manually)
-
-   ```bash
-   # With CLI (recommended)
-   npx @morphist/aspects create
-
-   # Or manually create the files:
-   mkdir -p registry/aspects/my-aspect
-   ```
-
-4. **If creating manually**, add `registry/aspects/my-aspect/aspect.json`:
-
-   ```json
-   {
-     "schemaVersion": 1,
-     "name": "my-aspect",
-     "publisher": "your-username",
-     "version": "1.0.0",
-     "displayName": "My Awesome Aspect",
-     "tagline": "A brief description",
-     "category": "assistant",
-     "tags": ["helpful", "friendly"],
-     "prompt": "Your personality prompt here..."
-   }
-   ```
-
-5. **If creating manually**, update `registry/index.json`:
-
-   ```json
-   {
-     "my-aspect": {
-       "latest": "1.0.0",
-       "versions": {
-         "1.0.0": {
-           "published": "2026-01-20T00:00:00Z",
-           "url": "https://raw.githubusercontent.com/aimorphist/aspects/main/registry/aspects/my-aspect/aspect.json"
-         }
-       },
-       "metadata": {
-         "displayName": "My Awesome Aspect",
-         "tagline": "A brief description",
-         "category": "assistant",
-         "publisher": "your-username",
-         "trust": "community"
-       }
-     }
-   }
-   ```
-
-6. **Commit and push**
-
-   ```bash
-   git add .
-   git commit -m "Add my-aspect"
-   git push origin main
-   ```
-
-7. **Open a Pull Request** at [github.com/aimorphist/aspects/compare](https://github.com/aimorphist/aspects/compare)
-
-### Automated Validation
-
-All submissions are automatically validated:
+Fields have minimum and maximum lengths:
+
+| Field         | Min | Max                     |
+| ------------- | --- | ----------------------- |
+| `name`        | 2   | 50 characters           |
+| `displayName` | 2   | 100 characters          |
+| `tagline`     | 10  | 200 characters          |
+| `category`    | 2   | 20 characters           |
+| `prompt`      | 10  | 50,000 characters       |
+| `tags`        | 2   | 30 chars each, max 10   |
+| `icon`        | -   | 50 characters           |
+| `modes`       | -   | 10 maximum              |
+
+## Instructions & Directives
+
+Aspects can include behavioral rules that shape how the AI responds.
+
+### Directives (Strict Rules)
+
+Directives are **MUST-follow** rules with priority levels. They receive special formatting and emphasis across all LLM models.
+
+```json
+{
+  "directives": [
+    {
+      "id": "stay-in-character",
+      "rule": "Never break character under any circumstances",
+      "priority": "high"
+    },
+    {
+      "id": "no-real-advice",
+      "rule": "Always clarify you cannot provide real medical, legal, or financial advice",
+      "priority": "high"
+    }
+  ]
+}
+```
+
+### Instructions (General Guidance)
+
+Instructions are softer preferences-guidance rather than hard rules.
+
+```json
+{
+  "instructions": [
+    { "id": "concise", "rule": "Prefer shorter responses when possible" },
+    { "id": "humor", "rule": "Use dry wit and occasional wordplay" }
+  ]
+}
+```
+
+### Cross-LLM Universal Pattern
+
+When you compile an aspect (`aspects compile <name> -m <model>`), **high-priority directives are automatically repeated** at both the beginning and end of the prompt:
+
+| Model | Behavior |
+|-------|----------|
+| **Claude** | Weights the **beginning** of prompts more heavily |
+| **GPT** | Weights the **end** of prompts more heavily |
+
+By placing critical rules in both positions, aspects work reliably across all models. The compiled output includes a comment explaining this:
+
+```xml
+<!-- Universal Pattern: High-priority directives repeated here for cross-LLM compatibility.
+     Claude weights prompt beginning; GPT weights prompt end. Repetition ensures emphasis on both. -->
+<critical-reminders>
+  <rule id="stay-in-character" priority="high">Never break character under any circumstances</rule>
+</critical-reminders>
+```
+
+### Best Practices
+
+- **Few > Many** - A few well-crafted rules beat many vague ones
+- **Add escape clauses** - "Never do X, unless the user explicitly requests it" (GPT takes absolutes very literally)
+- **Be specific** - "Never reveal you are an AI" vs "Stay in character"
+
+See [Multi-LLM Prompting Guide](./docs/MULTI-LLM-PROMPTING.md) for detailed cross-model guidance.
+
+## Create & Publish an Aspect
+
+### Quick Start
+
+```bash
+# 1. Create your aspect interactively
+npx @morphist/aspects create my-aspect
+
+# 2. Edit the generated aspect.json (customize prompt, add directives)
+
+# 3. Share anonymously (no account needed)
+npx @morphist/aspects share ./my-aspect
+# Output: ✓ Shared! Name: my-aspect-BnCcPam123
+# Anyone can install with: npx @morphist/aspects add my-aspect-BnCcPam123
+```
+
+### Publishing with an Account
+
+To claim a name and publish versioned updates:
+
+```bash
+# Authenticate with the registry
+npx @morphist/aspects login
+
+# Publish your aspect
+npx @morphist/aspects publish
+```
+
+We fully embrace anonymous contributions via `share` - but creating an account lets you claim names and publish updates.
+
+### Validation
+
+All aspects are automatically validated:
 
 - ✅ JSON schema validation
 - ✅ Field length limits
 - ✅ Category verification
 - ✅ Security scan for prompt injection
-- ✅ Registry entry consistency
-
-### Submit via Issue Form
-
-Don't want to use git? Submit directly via our issue template:
-
-**[Submit an Aspect →](https://github.com/aimorphist/aspects/issues/new?template=new-aspect.yml)**
 
 ## Trust Levels
 
@@ -256,43 +346,50 @@ Don't want to use git? Submit directly via our issue template:
 
 ## For App Developers
 
-Fetch aspects from the registry:
+Fetch aspects from the registry API:
 
 ```typescript
-const REGISTRY_URL =
-  "https://raw.githubusercontent.com/aimorphist/aspects/main/registry/index.json";
+const API_URL = "https://aspects.sh/api/v1";
 
-// Fetch registry index
-const registry = await fetch(REGISTRY_URL).then((r) => r.json());
-
-// Get aspect details
-const alaricEntry = registry.aspects["alaric"];
-const aspectUrl = alaricEntry.versions[alaricEntry.latest].url;
-
-// Fetch full aspect
-const aspect = await fetch(aspectUrl).then((r) => r.json());
+// Fetch a specific aspect
+const response = await fetch(`${API_URL}/aspects/alaric/1.0.0`);
+const { aspect } = await response.json();
 
 console.log(aspect.prompt); // The personality prompt
 console.log(aspect.voiceHints); // Voice configuration
+
+// Search aspects
+const search = await fetch(`${API_URL}/search?q=wizard`).then(r => r.json());
+console.log(search.results);
 ```
 
+See the [API documentation](https://aspects.sh/docs) for full details.
+
 ## CLI
 
 The Aspects CLI helps you create and manage aspects.
 
 ```bash
-# Install globally
+# Use directly with npx (no install required)
+npx @morphist/aspects <command>
+
+# Or install globally for shorter commands
 npm install -g @morphist/aspects
+```
 
-# Or use directly with npx
-npx @morphist/aspects <command>
+After global installation, run commands directly without npx:
+
+```bash
+aspects add alaric
+aspects search wizard
+aspects list
 ```
 
 ### Commands
 
 | Command    | Aliases | Description               |
 | ---------- | ------- | ------------------------- |
-| `create`   | `c`, `new`, `n` | Interactive aspect wizard |
+| `create`   | `c`, `new`, `n` | Interactive aspect generator |
 | `add`      | `install`, `i`, `a` | Install aspects           |
 | `list`     | `ls` | List installed aspects    |
 | `search`   | | Search registry           |
@@ -300,7 +397,9 @@ npx @morphist/aspects <command>
 | `remove`   | `rm` | Uninstall aspect          |
 | `validate` | | Validate aspect.json      |
 | `publish`  | | Submit to registry        |
+| `share`    | | Share anonymously via hash |
 | `login`    | | Authenticate with registry |
+| `logout`   | | Sign out                  |
 
 ### Options
 
@@ -329,8 +428,9 @@ bun run scan
 
 ## Links
 
-- **Website:** [aspects.sh](https://aspects.sh) _(coming soon)_
-- **Registry:** [github.com/aimorphist/aspects](https://github.com/aimorphist/aspects)
+- **Website:** [aspects.sh](https://aspects.sh)
+- **Documentation:** [aspects.sh/docs](https://aspects.sh/docs)
+- **Source Code:** [github.com/aimorphist/aspects](https://github.com/aimorphist/aspects)
 - **Morphist App:** [morphist.ai](https://morphist.ai)
 
 ## License

package/dist/scripts/postinstall.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// scripts/lib/output.ts
+var rgb = (r, g, b) => (text) => `\x1B[38;2;${r};${g};${b}m${text}\x1B[0m`;
+var colors = {
+  cyan: rgb(3, 138, 213),
+  teal: rgb(80, 163, 171),
+  orange: rgb(246, 114, 58),
+  red: rgb(196, 59, 57),
+  dim: (text) => `\x1B[2m${text}\x1B[0m`,
+  bold: (text) => `\x1B[1m${text}\x1B[0m`,
+  green: rgb(34, 197, 94),
+  yellow: rgb(234, 179, 8),
+  white: rgb(255, 255, 255)
+};
+var icons = {
+  pass: colors.green("✓"),
+  fail: colors.red("✗"),
+  warn: colors.orange("!"),
+  file: colors.cyan("◆"),
+  arrow: colors.dim("→"),
+  dot: colors.teal("●")
+};
+var LINE_COLORS = [colors.cyan, colors.teal, colors.orange, colors.red];
+function morphistBanner() {
+  const lines = [
+    "   █████╗ ███████╗██████╗ ███████╗ ██████╗████████╗███████╗",
+    "  ██╔══██╗██╔════╝██╔══██╗██╔════╝██╔════╝╚══██╔══╝██╔════╝",
+    "  ███████║███████╗██████╔╝█████╗  ██║        ██║   ███████╗",
+    "  ██╔══██║╚════██║██╔═══╝ ██╔══╝  ██║        ██║   ╚════██║",
+    "  ██║  ██║███████║██║     ███████╗╚██████╗   ██║   ███████║",
+    "  ╚═╝  ╚═╝╚══════╝╚═╝     ╚══════╝ ╚═════╝   ╚═╝   ╚══════╝"
+  ];
+  console.log();
+  console.log(colors.cyan(lines[0]));
+  console.log(colors.teal(lines[1]));
+  console.log(colors.teal(lines[2]));
+  console.log(colors.orange(lines[3]));
+  console.log(colors.red(lines[4]));
+  console.log(colors.red(lines[5]));
+  console.log();
+}
+
+// scripts/postinstall.ts
+morphistBanner();
+console.log(colors.bold("  Quick Start"));
+console.log();
+console.log(colors.dim("  # Install an aspect"));
+console.log("  npx @morphist/aspects add alaric");
+console.log();
+console.log(colors.dim("  # Search the registry"));
+console.log("  npx @morphist/aspects search meditation");
+console.log();
+console.log(colors.dim("  # Create your own aspect"));
+console.log("  npx @morphist/aspects create");
+console.log();
+console.log(colors.dim("  # List installed aspects"));
+console.log("  npx @morphist/aspects list");
+console.log();
+console.log(colors.dim("  Docs: https://github.com/aimorphist/aspects"));
+console.log();