syntax-orchestrator

Tier 0 public distribution of the synt-mx engine with a built-in Local Hive Dashboard.

This repository provides a local-first telemetry engine that receives, stores, and serves project logs for development workflows. In standalone use, it acts as a lightweight developer documentation system, decision tracker, and portfolio generator for projects that evolve over multiple sessions.

Engine Role

The engine runs on Port 3005 by default and acts as both local data intake and a local project dashboard.

• Base URL: http://localhost:3005
• Local dashboard: GET /local-dashboard
• Health endpoint: GET /health
• Ingestion endpoints:
  • POST /v1/entries/engineering
  • POST /v1/entries/journal
• Read endpoints:
  • GET /entries
  • GET /entries?project=my-project&scope=feature&limit=20
  • GET /v1/entries/journal
  • GET /api/projects
• Task orchestration endpoints:
  • POST /api/service-request
  • GET /api/agency-ops
  • POST /api/manager-approve
  • GET /api/agent-tasks
  • POST /api/agent-tasks/:taskId/status
  • POST /api/agent-tasks/:taskId/log

Standalone Developer Value

You do not need agent playpens or an IDE-integrated coding agent to get value from syntax-orchestrator.

With only this repository installed, you can:

• log implementation decisions over time with syntax log
• store project-scoped engineering history in local SQLite
• browse projects in the dashboard by most recent activity
• open a single project's recent decisions, rationale, blockers, and tags
• create a lightweight record of work across long-running projects where development happens in bursts instead of one uninterrupted sprint

This is especially useful for developers who:

• work with browser agents and paste code into the editor manually
• move quickly without an agent, but still need an accurate decision trail over time
• want a local portfolio of what changed, why it changed, and where friction appeared

Current limitations:

• engineering logs are project-aware in the dashboard, but journal logs are still global
• the task workflow remains available behind an Advanced section and is intentionally de-emphasized for portfolio-first browsing
• static site generation is not included — this distribution ships a minimal HTML harvest only (npm run harvest). A proper static site generator is a planned extension, not a built-in feature of this PoC.

Adding a Static Site Generator

Once you have this repo cloned into a workspace, another agent or developer can add full static site generation as a follow-on task. We recommend 11ty (Eleventy) — it integrates cleanly with the existing JSON outputs from the engine and requires minimal boilerplate.

Ask your coding agent: "Add 11ty static site generation to syntax-orchestrator using the harvest data in data/ as the source."

Primary Bridge: syntax CLI

This repository ships a built-in interactive CLI (syntax) that replaces the legacy ddh npm package as the primary human bridge into Port 3005.

Bridge pattern:

1. Developer runs syntax log from any project terminal.
2. CLI collects a structured prompt and posts to Port 3005.
3. Engine stores the entry in local SQLite and exposes it through read endpoints.

One-time Setup

1. Register the command globally via npm link:

From the syntax-orchestrator directory:

npm link

This creates a global syntax symlink pointing to bin/syntax.js. You only need to run this once per machine.

2. Save your auth token:

The CLI uses the JWT_SECRET from your .env to authenticate with the engine. Save it once:

syntax setup

You will be prompted for the secret. It is saved to ~/.syntax-cache.json and never sent anywhere except http://localhost:3005.

The default standalone target should be http://localhost:3005.

Alternatively, export it in your shell profile:

export SYNT_TOKEN="your-jwt-secret-here"

Logging a Decision

Navigate to any project folder and run:

syntax log

You will be guided through:

Prompt	Notes
Project	Defaults to the current directory name or your last logged project
Scope	Choose from: prototype, boilerplate, feature, refactor, integration, database, docker, environment, auth, ui/ux, docs
Summary	Required. What you did.
Key Decision	Optional. If provided, a Rationale prompt follows automatically.
Friction	Optional. If filled, blocked is appended to your tags automatically.
Tags	Comma-separated. Optional.

Total time from syntax log to saved vault entry: under 20 seconds.

After logging, open the dashboard and select the project you just updated:

xdg-open "http://localhost:3005/local-dashboard"

The standalone dashboard will:

• group engineering logs by project
• show latest activity first
• highlight projects with blockers
• render a deep-linkable project detail view through ?project=<name>

Offline Fallback

If the engine is not running when you log, the entry is saved locally to:

data/offline-queue.json

Once the engine is back up, flush the queue:

syntax flush

Environment Variables

Variable	Default	Purpose
SYNT_API_URL	http://localhost:3005	Override the engine URL
SYNT_TOKEN	(from syntax setup)	Auth token (JWT_SECRET)

Quick Start

1. Install dependencies:

npm install

2. Configure environment:

cp .env.example .env

Set JWT_SECRET in .env before first run.

3. Run development server:

npm run dev

Port 3005 ownership note: this distribution defaults to port 3005 to avoid collision with PM2-managed synt-mx on port 3000. Override if needed.

4. Verify health:

curl http://localhost:3005/health

5. Open local dashboard:

xdg-open http://localhost:3005/local-dashboard

6. Create your first project-scoped engineering log:

syntax log

7. Generate a minimal static snapshot (optional):

npm run harvest

Harvest output is written to data/harvest-site/:

• index.html — basic HTML mirror
• data/hive-status.json
• data/bee-profiles.json

Note: This is a minimal harvest, not a full static site. If you want a proper portfolio site with project pages, add a static site generator after cloning. We recommend 11ty. Ask your coding agent to wire it up using the harvest JSON as source data.

Project-Aware Browsing

syntax-orchestrator now treats the local dashboard as a project index for standalone users.

Key behavior:

• GET /api/projects returns project summaries ordered by latest activity
• GET /entries?project=<name>&scope=<scope>&limit=<n> returns filtered engineering logs for one project
• GET /local-dashboard?project=<name> opens a deep link directly into that project's detail view
• the dashboard includes a scope filter and timeline window (7d, 30d, 90d, all) for focused review
• optional task workflow is collapsed under an Advanced section to keep project browsing primary

This makes the repo useful even without any agent task manager or playpen repos. The dashboard becomes the primary place to review project history over time.

Mac Setup (VS Code + zsh)

Use this section if you are installing on a fresh Mac (for example, a Mac mini M4) and have junior-level terminal experience.

1. Install core tools

Open Terminal (zsh) and install Homebrew if needed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Git and Node.js LTS:

brew install git node

Check versions:

git --version
node --version
npm --version

2. Install VS Code

Install Visual Studio Code from the official site, then install the code command in zsh:

1. Open VS Code.
2. Press Command+Shift+P.
3. Run: Shell Command: Install 'code' command in PATH.

Verify:

code --version

3. Clone and open this repository

mkdir -p ~/githubs
cd ~/githubs
git clone https://github.com/walrusWebDev/syntax-orchestrator.git
cd syntax-orchestrator
code .

4. Configure environment

Create your local env file:

cp .env.example .env

Generate a strong JWT secret:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

Paste that value into .env as JWT_SECRET=....

5. Install dependencies and start the engine

npm install
npm run dev

In a second Terminal tab, verify health:

curl http://localhost:3005/health

6. Link CLI globally and save token

From the repo folder:

npm link
syntax setup

When prompted, paste the same JWT_SECRET from .env.

7. Test from any project folder

cd ~/githubs
mkdir -p my-python-app
cd my-python-app
syntax log

If successful, your entry is saved to the local SQLite vault through Port 3005.

Common troubleshooting

• 401 Unauthorized:
  • Re-run syntax setup and confirm the token exactly matches the running engine's JWT_SECRET.
• Port 3005 already in use:
  • Another service may own it. Stop that service, or run this engine on another port:

PORT=3010 npm run dev
SYNT_API_URL=http://localhost:3010 syntax log

• Engine offline:
  • syntax log will queue the payload in data/offline-queue.json. Run syntax flush after the engine is back online.

Tier 0 Defaults

• Local SQLite path defaults to ./data/syntax-orchestrator.db.
• The repository bootstraps schema on first run.
• A placeholder seed user with id 1 is created automatically.
• If payloads reference a new user id, the repository auto-seeds that user to avoid first-boot foreign key failures.

Notes for Public Distribution

• No runtime SQLite database files are included.
• No private .env values are included.
• No inherited git history from source repos is included.

See DISCLAIMER.md before using this in real environments.