diff --git a/src/model/howto-workflow.md b/src/model/howto-workflow.md
index f918863..ca2191f 100644
--- a/src/model/howto-workflow.md
+++ b/src/model/howto-workflow.md
@@ -36,7 +36,7 @@ const howto = {
     { title: "Step 2", text: "...", order: 2 }
   ]
 };
-`o`
+```
 
 Advantages:
 
diff --git a/src/model/howto.ts b/src/model/howto.ts
index 8fa7fcd..e848a61 100644
--- a/src/model/howto.ts
+++ b/src/model/howto.ts
@@ -5,7 +5,7 @@ import { sync as read } from '@polymech/fs/read'
 import { sync as exists } from '@polymech/fs/exists'
 import { sync as mkdir } from '@polymech/fs/dir'
 import { sync as rm } from '@polymech/fs/remove'
-import { IHowto, Image } from './howto-model.js';
+import { IHowto, Image, IOATag } from './howto-model.js';
 import type { Loader, LoaderContext } from 'astro/loaders'
 import { sanitizeFilename } from "@polymech/fs/utils"
 import { filter as language } from "@/base/kbot.js";
@@ -130,12 +130,10 @@ export const howtos = async () => {
   howtos = howtos.filter((h) => h.moderation == 'accepted');
   const tags = data.v3_tags;
   howtos.forEach((howto: IHowto) => {
-    const howtoTags: any = [];
+    const howtoTags: IOATag[] = []
     for (const ht in howto.tags) {
-      const gt: any = tags.find((t) => t._id === ht) || { label: 'untagged' };
-      if (gt) {
-        howtoTags.push(gt.label || "");
-      }
+      const gt: any = tags.find((t) => t._id === ht) || { label: 'untagged' }
+      gt && howtoTags.push(gt.label || "")
     }
     howto.user = data.v3_mappins.find((u) => u._id == howto._createdBy);
     howto.tags = howtoTags;
diff --git a/src/model/todos-workflow.md b/src/model/todos-workflow.md
index 3dec0a6..6911132 100644
--- a/src/model/todos-workflow.md
+++ b/src/model/todos-workflow.md
@@ -1,12 +1,33 @@
-## Todos
+## Goal
 
-- we use Typescript, ESM, minimal dependencies, functional programming
-- code : dont document or comment, return just the code, ready to go
-- no additional dependencies
+Design a better interface/model for a **file-based how-to workflow** system. The aim is to improve how-tos via IDE or API. Use **TypeScript**, **ESM**, **functional programming**, and **zero dependencies**.  
 
-## Todos
+> 🔧 **Code only**: return minimal, ready-to-use TypeScript code. No comments, no explanations, no external packages.
 
-- [ ] suggest a better interface/model that allows for a file based workflow, improving howtos via IDE or API. For example, there should be meta data supporting versioning/staging descriptions (including steps), by humans or AI models. The author may want to choose between different suggestions and version and pin it. Also, that versions are being stored on discs, for comparsion. The system provides a folder for each howto. Save it to ./howto-ex.ts (extend  ./howto-model.ts), dont implement or design storage related interfaces !
-- [ ] currently problematic : steps are stored as array, with no explicit order.
-- [ ] each version should track : author or model, time, status: enabled, under review, new, discarded
-- [ ] document/explain all in ./howto-workflow.md
+---
+
+## Requirements
+
+- ✅ Each how-to is stored in its own **folder**.
+- ✅ Output your interface/model in `./howto-ex.ts` (extending `./howto-model.ts`).
+- 🚫 Do **not** implement or design any storage logic.
+
+---
+
+## Key Design Improvements
+
+- Replace the current `steps: Step[]` (unordered) with a model that makes **step order explicit**.
+- Include **metadata for versioning/staging**:
+  - version history saved to disk (for comparison)
+  - authored by human or AI
+  - status: `enabled` | `under_review` | `new` | `discarded`
+  - timestamped entries
+- Support multiple **suggestions** per step/version.
+  - Allow the author to **choose**, **pin**, and **track** them.
+
+---
+
+## Deliverables
+
+- [ ] `./howto-ex.ts`: new interfaces/models extending `./howto-model.ts`
+- [ ] `./howto-workflow.md`: explain the rationale behind your design choices