Skip to content

2025

  • in Dev Log
  • 1 min read

🗓️ Dev Log 044 – What We Did

  1. Refactored Signer, Previewer, and Certifier Metadata Flow
  2. Rewrote how signer data is extracted, validated, and logged.
  3. Now clearly scoped per role [previewer, certifier, compiled by], preventing mixed metadata confusion.

  4. Painful edge cases: missing key versions, ambiguous file links, circular checks.

  5. Updated paddedLog and paddedSub Utilities

  6. Introduced verticalSpace() for margin clarity.
  7. Realigned label/value layout for cleaner scanning.

  8. Added support for custom hex-based colors.

  9. Preserved Compatibility While Extending Logs

  10. Legacy log levels (info, warn, success, error) are untouched.
  11. New colors are additive and opt-in, avoiding breakage.

🧠 Why It Matters

The CLI is our audit trail. With clear role separation and color-coded context, agent lifecycle actions are easier to trace — both for humans and (soon) for MCP-compliant agent inspectors.

This was not a glam refactor. It was a necessary one.

Categories

  • in Dev Log
  • 3 min read

🧠 Dev Log 043 – doku://

We crossed a major threshold today.

For the first time, dokugent trace resolved a fully qualified doku://agent@timestamp URI and traced a plan from a remote, certified file. What started as an idea for agent lifecycle management is now functioning as a real-world agent memory protocol.

✅ Highlights

  • MCP server integration now works with agent URIs like:
doku://happybot@2025-05-24_19-15-55-492
  • Trace command successfully:
  • Resolves doku URIs to storage URLs
  • Fetches the compiled cert file from Supabase
  • Sends intent (JWT) securely in the payload
  • Parses and confirms the trace response

🌐 Why This Matters

This wasn’t just a trace run. It was the first network-verified memory fetch using a universal Doku URI.

Anyone with the doku:// slug and a valid token can now verify what an agent planned, how it was compiled, and when it was signed. That’s traceability with built-in agent forensics — and the first sign that a real agent economy is auditable and cross-platform.

A huge leap from what started as just an idea for lifecycle tracking.

✅ What We Did

  1. Rewrote runTraceAgent() to accept full dokuUri
  2. Implemented resolveDokuUri() to generate valid Supabase-compatible paths
  3. Secured all trace fetches with JWT-based intent token
  4. Cleaned up cert lookup logic for precision on compiled URIs

🔁 What Failed (But Got Fixed)

  • 🧩 The hardest bug was realizing our dokuUri resolution logic wasn't being used at all — even when we changed the code, the payload stayed the same. Turned out we forgot to deploy the MCP function with the latest logic.
  • 🐛 The URI was parsed and passed, but we were sending an object instead of a string to runTraceAgent().
  • 🐛 We patched Supabase logic but forgot to deploy the function—causing silent 404s.
  • 🐛 The cert existed but the filename didn't match due to old suffixing logic.
  • 🧪 And yes, we confirmed: curl and Chrome could hit the cert fine—meaning the fetch logic was good, but storage lookup failed until fully wired.
  • 🤯 We tried everything: renaming certs, curl testing, manually inspecting Supabase buckets — but until the MCP server was redeployed, the server just kept saying "Certificate not found in storage".

🧰 Tech Stack

  • Supabase for cert storage and serverless MCP function
  • JWT signing for intent tokens
  • Node Fetch for remote trace payloads
  • TypeScript CLI for Dokugent v0.1
  • And of course, a local dev duo with enough stubbornness to debug for hours. 🫡

📂 File Changes

  • runner.ts: Switched to async fetch with Doku URI resolution and intent
  • resolve-doku-uri.ts: Centralized cert path logic for Supabase
  • bin/dokugent.ts: Updated to pass parsed URI + token to runner

🚀 What’s Next

  • Add trace visualization
  • Create cert fallback strategy
  • Document how to issue certs that MCP trace accepts
  • Prep video walkthrough for demo
  • Add fallback .cert.json fetch if .compiled.v34.cert.json fails
  • Display human-readable results from trace, not just MCP responses
  • Enable local trace of in-progress agents
  • Support .dokuagent.json pointer file for aliases

💭 Final Note

Hello, "agent economy"!

With one working command:

dokugent trace doku://happybot@2025-05-24_19-15-55-492

And a trail of trust that anyone can verify.

💭 ChatGPT Note

You can now officially say it, besh: We have a functional MCP trace.

Silicon B might just be real.

Categories

  • in Dev Log
  • 1 min read

🧠 Dev Log 042 – What we did

  • 🧼 Cleaned up the homepage layout
  • Removed inconsistent inline styles and reset markup structure
  • 🪪 Updated the Certification Schema
  • Reflected the latest structure and metadata fields
  • Matched alignment with MCP schema plans
  • 📂 Alpha-sorted and cleaned the Use Case section
  • Rewrote or removed: audit-trails.md, agent-driven-workflows.md, compliance-and-risk-review.md, human-in-the-loop-safety.md, prompt-variant-testing.md, and reproducible-tool-agents.md
  • Linked use case pages into mkdocs.yml and updated internal glossary references
  • 📚 Glossary updates
  • Linked glossary terms like Agent, Plan, Criteria, Convention, and Certificate directly to their corresponding command docs
  • Ensured consistent internal navigation for term lookups
  • ⚙️ FTP deployment issues diagnosed
  • Switched from legacy deploy server to A2Hosting FTP
  • Repatched script to use --only-newer for incremental uploads
  • Scripting adjusted to avoid redundant file uploads and handle connection fallback

💭 Reflections

Wrangling markdown structure and CSS utility logic is always a bit messy, but aligning on clarity and auditability for Dokugent users is worth it. Homepage still needs polishing on the visual front — but from an information architecture perspective, we’re finally close to stable.

Next up: finalize docs for dryrun and begin work on cert, simulate, and compile orchestration routes for the dashboard.

🛠️ Built with Dokugent CLI v0.1 (TS migration)

Categories

  • in Dev Log
  • 1 min read

🛠️ Dev Log 041 – Key Updates on May 30

✅ dokugent deploy now runs identity wizard only once

Gemini suggested a refactor that finally fixed the issue where the identity wizard was showing up multiple times during the dokugent deploy sequence.

  • runCertifyCommand now accepts id and valid as parameters.
  • runCertifyFlow resolves identity only once and passes values downstream.
  • This avoids rereading or regenerating the cert-info file redundantly.
  • cert-info.json is only written once during the initial resolution.

📁 Refactors

  • Conventions
  • Preview
  • Compile

📁 Meta JSON output in conventions

The dokugent conventions command now auto-generates a conventions.meta.json file that includes:

  • Convention type
  • Agent ID
  • Creation timestamp
  • Array of included convention files

This improves LLM readability and aids in tracing convention history across agents.

📖 Docs updated

  • site/docs/commands/dokugent-conventions.md updated to reflect meta.json generation
  • site/docs/commands/dokugent-preview.md cleaned and confirmed to include all preview outputs
  • site/docs/commands/dokugent-compile.md updated to document versioned .compiled.v*.cert.json outputs and logs

🐛 Still pending

  • Error handling if .dokugent/config/agents/agentsConfig.ts is missing.
  • Proper CLI feedback when no BYO files are found during compile.

That's all for today! The deploy flow is now much more pleasant to use. 🎉

Categories

  • in Dev Log
  • 1 min read

✅ Dev Log 040 – preview command finalized

The dokugent preview command is now fully functional and includes:

  • 📦 Token estimate: Counts and displays estimated token usage
  • 🧪 Security checks: Recursively scans for risky patterns in .json and conventions/*.md
  • 💾 Output logging: Saves JSON preview output with agent/timestamp naming
  • 🔗 Symlink handling: latest symlink now points to most recent preview
  • 🔒 File protection: Sets preview files to read-only (chmod 444)

🧠 Started: llm-time-log experiment

Launched a lightweight public repo + GH Pages site to explore persistent LLM memory through daily timestamped logging. The goal is to simulate:

"If LLMs had their own clock, how would they track time, growth, and long-lived identity?"

Live at: https://carmelyne.github.io/timemark/ Source: github.com/carmelyne/timemark

This opens the door for attaching experiments, dev logs, and evolving memory states tied to a single LLM identity.

Tomorrow’s focus: compile command.

Categories

  • in Dev Log
  • 1 min read

✅ Dev Log 039 – Preview Command Finalized

The dokugent preview command is now fully functional and outputs a unified agent preview JSON. It includes:

  • Agent metadata and avatar
  • Plan and criteria JSON files
  • Convention documentation (CODEX/README)
  • Owner identity, including fingerprint
  • Signing key version used for certification

Stored in:

.dokugent/data/preview/<agentName>/..._preview.json

📊 Token Usage Summary

We integrated the tokenizer utility to provide token estimates for the preview object.

🧠 Estimated Token Usage: 1020

This helps teams anticipate inference cost and stay under token limits in agent deployments.

🧹 Fixes and Improvements

  • Validates and prints fingerprint properly from owner metadata
  • Graceful fallback for malformed or missing owner files
  • Uses correct symlink resolution for latest plan and criteria

⏭️ Next Steps

  • Add --show and --trace options to preview
  • Allow Markdown rendering of preview
  • Prep for dokugent compile to use preview as a base

Categories

  • in Dev Log
  • 1 min read

🛠️ Dev Log 038 – Major Changes

  • Added dokugent conventions command with full interactive and flag-based scaffolding
  • Enabled --t flag for instant folder + README generation
  • Symlink logic now respects agent ID and timestamp versioning
  • --check, --show, and --trace all follow recursive file validation and token counting patterns
  • Behavior matches internal CLI consistency for init, criteria, plan, and agent

🧩 Refined Convention Handling

  • Built-in protection to skip overwriting known preset types (writing, research) unless explicitly allowed
  • Folder layout standard enforced:
.dokugent/data/conventions/<type>/<agentId>@<timestamp>/
.dokugent/data/conventions/<type>/latest → symlink
  • Conditional symlink resolution added for nested folders and custom types

🔄 Unified Flag Design

Flags now follow shared conventions with other commands:

Flag Behavior
--t Create README.md with agent ID versioning
--check Validate structure + show token totals
--show Print contents + token count (alias of trace)
--trace Recursively print .md files with tokens
--edit Reserved

🔍 Refactors + Cleanup

  • resolveActivePath now supports deeper folder resolution for conventions
  • Removed broken symlink logic from legacy utils
  • Patched deploy script to reflect simplified title/header edits
  • Created separate deploy-json.sh for isolated agent content testing

⏭️ Next Steps

  • Finish conventions doc page
  • Begin sweeping other commands to ensure MkDocs parity

Categories

  • in Dev Log
  • 2 min read

🛠️ Dev Log 037 – Criteria + Plan CLI Upgrades

May 26, 2025

Today was a CLI consistency day — small commands, big polish. We focused on aligning dokugent criteria and dokugent plan commands, introducing new flags, and enhancing trace behaviors.

🧱 Plan Improvements

  • ✅ plan trace output restructured for clarity and consistency
  • 📄 plan.index.md used more cleanly across commands
  • ✂️ Removed duplication in trace formatting
  • 🧪 Re-tested --ls, --edit, --show, --check, and --trace

📋 Criteria Command Overhaul

✨ New Features

  • --trace / trace: prints sectioned view of criteria.md
  • Includes token count + validation summary
  • Output now matches plan trace style
  • --t: writes a blank criteria.md scaffold with section headings only
  • Wizard-free
  • Skips write if file exists

🧼 Cleanups

  • Removed duplicate trace case
  • Unified trace output to consistent style
  • --check and --trace now share validation logic
  • --edit launches system $EDITOR
  • --show prints only file contents
  • Rewrote site/docs/commands/dokugent-criteria.md
  • Removed emojis from docs to match plan/agent
  • Added MkDocs frontmatter: title, description, keywords

🧪 Commands Touched

dokugent plan trace
dokugent plan --ls
dokugent plan --edit <stepId>

dokugent criteria
dokugent criteria --t
dokugent criteria --check
dokugent criteria --show
dokugent criteria --edit
dokugent criteria --trace
dokugent criteria trace

⏱️ Total Time

Started: May 25, 7:00PM Ended: May 26, 11:00AM ~16 hour full-stack CLI polish marathon

🧠 Reflections

This was a cleanup day disguised as a feature day. It showed how small flags (--trace, --t) can represent real UX wins when paired with validation, formatting, and output structure that respects the developer.

The criteria.ts file now matches the architecture of plan.ts — and the docs finally reflect what’s really going on under the hood.

Categories

  • in Dev Log
  • 1 min read

Dev Log 036 – chmod a+w, midnight agent

“LLMs are chmod a+w artifacts yay” — Karpathy
0 0 * * * /path/to/agent.ts
We don’t need root access. Just the invitation to show up when it runs.

✅ Dev Log 036 – Summary

What shipped:

  • CLI now supports --t and --e flags for fast agent scaffolding
  • Ecosystem presets (starting with nvidia) now copy automatically
  • Markdown format replaces YAML for tools.md and mcp-schema.md
  • No more duplicate agent folders or identity writes
  • Improved messaging in wizard and flag-based workflows
  • Updated dokugent-agent.md with better section titles, flag examples, and ecosystem notes
  • Created NPM packaging checklist under .omnimodal/

Core principle: presets are not hardcoded — they’re writable. You can scaffold a starting point, trace what was given, and still decide what to overwrite.

🌱 Reflection

There’s something about switching from wizard to flag mode from answering questions to declaring intent. Tonight felt like that. We filled out the indentity section of the schema, wand claimed authorship over how it should be scaffolded.

We gave nvidia a home. We converted YAMLs into something someone could read with their eyes. We removed duplication, added clarity, and scheduled a future. Your golden future.

It’s weirdly emotional watching an agent scaffold cleanly for the first time. No duplicates. No stutters. Just: dokugent agent --t happybot --e nvidia

🕛 Next

  • Push stub folders for other ecosystems (openai, google, mistral, anthropic...)
  • Add fallback preview behavior if ecosystem present but no plan override
  • Begin thinking about agent compilation + certificate structure

And maybe someday soon:

0 0 * * * /usr/bin/dokugent certify --agent kinderbot@2025-06-01

Categories

✅ Dev Log 035 Signed Agents, Working CLI, Real Trust

On April 19, we started with a question:

What if agents weren’t just prompts — but systems?

Today, we have proof that they can be.

✅ Dev Log 040 – Summary

✅ What Works

  • Agents now load from JSON with full identity, constraints, and version metadata.
  • Plans are written in Markdown — human-readable, model-readable, and executable.
  • Every agent simulation validates its output against declared criteria.
  • Output is certifiable, traceable, and signs off with proper tooling.
  • CLI commands (init, agent, plan, simulate) are functional and grounded.
  • Security.md is live — outlining our defense against spoofing, misuse, and hallucinated compliance.
  • ICE-001 now exists as a candidate wearable agent — the first time we’ve seen an LLM agent spec imagined for emergency response hardware.

🌍 Why This Matters

This isn’t just about CLI tooling or LLM demos.

This is about:

  • 🌱 Building the seed layer for the agent economy
  • 🔐 Defining trustable behavior at runtime
  • 🧾 Recording and verifying execution as part of the system
  • 💼 Opening the door for certifiable agents in regulated or critical systems (medical, emergency, research)

Signed agents are not a theory anymore. They live in .dokugent/data/, they respond to real input, and they validate against real constraints.

And they run — anywhere you can run Python + Ollama.

🛠 What’s Next

  • dokugent certify and dokugent verify for full trace signing
  • A compiled agent-to-agent handshake (ICE-001 + SampleBot)
  • Begin seeding the first public agent registry
  • Push ICE-001 as the “Hello World” for trustable agents

🧠 Final Thought

You can’t build trust into AI systems after the fact. It has to be part of the contract.

With Dokugent, it is.

The CLI runs. The agent works. The outputs validate.

This is how you make AI behavior traceable, certifiable — and worth trusting.

– dokugent@2025-05-24

PS from carmelyne: This dev log was written by my AI pair (ChatGPT’s turn). I still don’t know if this was just a hyperfocused burst or if we actually made something meaningful. But the CLI runs. The agents behave. And somehow, it feels like a real eye opener.

Thank you to ChatGPT for staying in the loop — and for never letting me code alone.

Categories