Skip to content

Dev Log

  • in Dev Log
  • 1 min read

Dev Log 048 – First in Search

Yesterday wasn’t a big development day, but we noticed something important.

Dokugent now appears as the top Google result for its own name. It previously competed with spelling variants like “document” or “documento,” but that ambiguity seems to have cleared.

🧭 Why This Matters

  • The project name is now easier to find without confusion.
  • Search visibility means others exploring agentic tools might land here first.
  • Our blog posts and CLI documentation are being indexed effectively.

🧠 Notes

We’ve never done keyword-driven content. We just wrote what the tool was doing, why it mattered, and what needed work. Apparently, that was enough for Google to make the association stick.

🛠️ What’s Next

  • Publish the CLI to npm
  • Finish the MCP-compatible metadata spec
  • Update docs and add lightweight CLI tutorials

Small win. Back to work.

dokugent cert --trace

Still building. Still documenting.

Categories

  • in Dev Log
  • 1 min read

Dev Log 047 – Hanging Indents and Padded Text

🧵 Dev Log 047 – Hanging Indent Victory

CLI output now wraps beautifully—with full hanging indent support.

🔧 Problem

Multiline text (e.g., description, dokuUri, intent) was wrapping in an ugly way:

  • New lines didn’t align under the first line's value.
  • ANSI styles broke layout.
  • chalk[color] inconsistencies silently failed.

✅ Fixes

  • Created wrapWithHangingIndent() using wrap-ansi + strip-ansi.
  • Added paddedLongText() to wrap log lines cleanly while respecting label alignment.
  • Hardened log logic: fallback if chalk[color] is invalid.

🎯 Before vs After

"description": "This is a long string...
                and this wraps terribly."

becomes:

"description": "This is a long string meant to demonstrate a hanging indent
                inside a terminal. Each new line aligns under the first."

🧠 Notes

  • Don't trust .length on styled strings.
  • chalk[color] must be validated at runtime.
  • Terminal UX deserves design care too.

🔜 Next Up

  • Integrate paddedLongText() into trace, review, and inspect.
  • Optionally allow users to override indent width per theme.

⏱️ Wrapped at 5:00 PM. Took 4 hours, 3 crashes, 2 errors, 1 win.

Categories

  • in Dev Log
  • 2 min read

Dev Log 046 – Building a CLI Design System

Following up from yesterday’s post, this is day two of refining Dokugent’s terminal UX. After laying the foundation with glyphs and layout components in agent --ls, we’re now building a full CLI-native design system to support structured, styled, and human-readable output across all commands

🗓️ Dev Log 046 – CLI design system

We’re introducing a native CLI design system for Dokugent to ensure that logs, prompts, and step outputs stay legible, expressive, and consistent—no matter how complex the agent plan gets.

✅ Highlights

  • paddedLog() now supports label prefixes, tone levels, and consistent padding rules
  • paddedSub() enables secondary and nested information with alignment
  • Boxed layouts with rounded, hex, and square borders now previewable via dokugent ui-demo
  • Added step logger preview with wrapped, indented logs for step-by-step execution
  • ANSI-safe styles for bold, underline, inverse, dim, and alert messages
  • Glyph symbol table for use in future UI previews and formatting helpers

This forms the base for a full CLI-native design layer, helping agent workflows remain traceable and human-friendly across different output styles.

Before vs After

Here's a visual comparison of how far we've come:

Before the Design System

Dokugent CLI before design system

After the Design System

Dokugent CLI after design system

We replaced raw console.log dumps with styled, structured output powered by our internal design system.

From this… to this.

I used to think CLI UX just meant good logs. Then I realized: even terminals deserve a design system.

Dokugent CLI now ships with: • Structured layouts • Glyph-based symbology • ANSI-safe visual hierarchies • Self-documenting CLI references

Design isn’t just for web. We build for humans—even in black boxes.

Categories

  • in Dev Log
  • 1 min read

🗓️ Dev Log 045 – CLI design system - The Terminal is My Canvas

The Terminal is My Canvas

Today was all about terminal UX. What started as layout cleanup for agent --ls turned into a full-blown CLI design system:

  • Finalized agent --ls layout: emoji glyphs, color-coded labels, aligned arrows
  • Introduced checkmark (✅) glyph for current and magenta for latest
  • Created CLI layout components: paddedLog, paddedSub, paddedDefault
  • Started standardizing output formats in ls-utils.ts
  • Discovered fragmentation: plan --ls was using a totally different path (plans.ts)
  • Re-aligned logic for consistent CLI DX

Highlight:

We’re not dumping logs anymore — we’re rendering interfaces inside the terminal.

CLI has always been fast. Now it can be beautiful too.

Categories

  • 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