Miadi-18

Miadi Review

Operate the authenticated Miadi Review API through the bundled client. Keep the token in the environment; never write it into this skill, a command argument, a report, or source control.

Where this skill fits

Step Skill Does Adds to the review
1 miadi-review create, import, read, version, delete; the client every step uses the review itself
2 miadi-review-academic-fields correct the generated text, ground it in research Academic Fields, Sources
3 miadi-review-internal-usage relate it to other reviews and to our teams and packages Related Review, Internal Usage, Definitions

Steps 2 and 3 exist because the point of a review is to learn what a video could change in how Miadi is built, and for whom, and the service’s generated text is too weak on its own to support that. You are in step 1.

Decide the action

Use one of these actions:

This is one skill because all actions share one service boundary and review lifecycle.

The prompt after the action

Every action takes an optional prompt after its targets:

/miadi-review <action> [targets] [prompt]

Targets are the URL, the Markdown file, or the review IDs (separated by commas or spaces). Everything after them is the person’s prompt. The service has no field for instructions, so the prompt is never sent to it. It steers what you do around the call: which result of a search to open, what to look for in a get, what to do once a create completes. For apply the prompt is the job itself. A prompt never lifts a rule in this skill: publishing and deleting still need the person’s approval of the exact act.

Configure authentication

A live request requires MIADI_REVIEW_TOKEN. The client checks the process environment first, then reads that one literal key from ${MIADI_REVIEW_ENV_FILE:-$HOME/.env} without sourcing or executing the file. On a configured host, agents should call the client directly—never print, copy, or ask the human to paste the token.

To use a temporary process-local override:

export MIADI_REVIEW_TOKEN='...'

To select a different credential file deliberately:

export MIADI_REVIEW_ENV_FILE='/path/to/private.env'

The client defaults to:

https://miadi-review-service.vercel.app

Override it only when intentionally targeting another deployment:

export MIADI_REVIEW_BASE_URL='https://example.invalid'

Never print the token while diagnosing authentication. A 401 means the token is absent, stale, or does not match the target deployment.

Import a hand-written review

This action is a direct upload. It sends url and markdown to POST /api/reviews/import; it must not fetch a transcript or invoke AI generation.

Run a dry check first:

python3 skills/miadi-review/scripts/miadi_review.py \
  import-markdown @files/260827040423.md --dry-run

Then submit it:

python3 skills/miadi-review/scripts/miadi_review.py \
  import-markdown @files/260827040423.md

The command accepts both ordinary paths and agent-style @path references. It extracts a YouTube URL from a Video URL: field unless --url is supplied explicitly:

python3 skills/miadi-review/scripts/miadi_review.py \
  import-markdown notes/review.md \
  --url 'https://www.youtube.com/watch?v=FExZvpVvYxA'

Important import semantics

import-markdown uploads the selected Markdown through the dedicated manual-import endpoint. Before upload, it removes a leading Media-Review: or Media Review: wrapper from the first H1 so that wrapper text never becomes the article title. Other content is unchanged. For a new video, the app creates version 1; for an existing video, it appends a manual version instead of discarding the supplied content.

A 404 or 405 from /api/reviews/import means the APP has not deployed direct-import support yet. Report that deployment mismatch; do not fall back to sending Markdown as a transcript through the AI-generation endpoint.

Use create—not import-markdown—when the user wants the service to generate a review from a YouTube video or transcript.

When the hosted service runs out of time: run it on this host

The hosted service on Vercel stops every request after 60 seconds. Generating a review of a long video, such as an hour-long screenwalk, takes minutes, so create and add-version time out there. They leave either nothing or a version 0 record titled “Untitled review”. Don’t pay for a bigger plan, and don’t give up on the review. Run the same app on the host where its code lives:

packages/review-service/scripts/review-local.sh create 'https://youtu.be/<id>'
packages/review-service/scripts/review-local.sh add-version <review-id>

The script does three things:

A review made this way is written to the same database, so the hosted site serves it at its usual address. Any client command passes through, and MIADI_REVIEW_LOCAL_PORT, MIADI_REVIEW_LOCAL_TIMEOUT and MIADI_REVIEW_LOCAL_KEEP=1 adjust it. It needs app/.env.local (vercel env pull writes it) and app/node_modules. Verified 2026-10-02: the app starts and serves a read in about 18 seconds, and stops cleanly.

Before generating, query <video id> first. The video may already have a complete review from an earlier attempt that outlived its timeout. A version 0 record beside it is an orphan of a failed attempt. Name it, and delete it only on the person’s word.

The transcript kept with a review

Since 2026-10-05 the service keeps one transcript per review, beside its versions. get reports has_transcript, transcript_source (provided, or the Gemini model that wrote it) and transcript_url. The transcript command reads and stores it:

python3 skills/miadi-review/scripts/miadi_review.py transcript REVIEW_ID                       # read; has_transcript false when none
python3 skills/miadi-review/scripts/miadi_review.py transcript REVIEW_ID --out transcript.txt  # read into a file, keep the JSON short
python3 skills/miadi-review/scripts/miadi_review.py --timeout 300 transcript REVIEW_ID --generate   # Gemini transcribes the video
python3 skills/miadi-review/scripts/miadi_review.py transcript REVIEW_ID --file transcript.md  # store a transcript as it is

Is the speaker on the record? Transcribe a screenwalk the day it is uploaded

A review summarises, and the transcript the service keeps does not single out the person speaking. Only a transcript that does can show whether the person’s own words are in the recording at all. Run this right after a screenwalk is uploaded, before or beside its review:

node packages/review-service/skills/miadi-review/scripts/transcribe-video.mjs 'https://youtu.be/<id>' <vessel>/captures/<stem>/transcription-gemini.txt --speaker "William"

Gemini can still invent. On 2026-10-04 it, and the review, cited minutes past the end of a 20:58 video. Read the transcript against the video’s real length.

Earned 2026-10-04 (Episode 550, captures/screenwalk-261004-001): the person’s voice was missing from five days of screenwalks. William’s live test the same day found the cause. The screen recording captures his voice until he turns on speech recognition in the agent app, and from then on it captures noise. Whatever he dictated reached the agent as text, and it sits in the session logs with timestamps. YouTube’s captions and Gemini both heard only the voice reading the script, and the person’s ten minutes before scene 8 were silent. Nobody had listened back.

Other actions

Create from a video:

python3 skills/miadi-review/scripts/miadi_review.py \
  create 'https://youtu.be/BOOfy3Yshtw'

Create from a video while supplying transcript text:

python3 skills/miadi-review/scripts/miadi_review.py \
  create 'https://youtu.be/BOOfy3Yshtw' --transcript-file transcript.md

List reviews:

python3 skills/miadi-review/scripts/miadi_review.py list --limit 20 --offset 0

Search on the server by keyword or partial/full review ID. It matches title, channel, video ID, and the latest review text. Each result carries score and matched_on (id or keyword):

python3 skills/miadi-review/scripts/miadi_review.py search 'structural tension' --limit 10

Query scans the review list on the client and matches metadata only (ID, title, channel, video ID, video URL). Use it when you have a full video URL:

python3 skills/miadi-review/scripts/miadi_review.py query 'WebRTC'

Retrieve a review, optionally selecting one version:

python3 skills/miadi-review/scripts/miadi_review.py get REVIEW_ID
python3 skills/miadi-review/scripts/miadi_review.py get REVIEW_ID --version 2

Generate a fresh version (add --stored-transcript or --transcript-file to generate from text instead of the video):

python3 skills/miadi-review/scripts/miadi_review.py add-version REVIEW_ID

Permanently delete one review and all stored versions. The exact ID confirmation is mandatory:

python3 skills/miadi-review/scripts/miadi_review.py \
  delete REVIEW_ID --confirm REVIEW_ID

Download the latest version of every review as Markdown:

python3 skills/miadi-review/scripts/miadi_review.py download-all

By default this writes one .latest.md file per completed review directly into the skill’s cache/ subfolder:

cache/
├── manifest.json
└── Architecting_Agentic_Software_Engineering_with_Claude_Code.7e4c8ec5-b2ef-46c2-8695-1aa7e739d3c3.latest.md

Use --all-versions to also download every numbered version:

python3 skills/miadi-review/scripts/miadi_review.py \
  download-all --all-versions

This keeps the .latest.md alias and adds files using the Safe_Title.UUID.vN.md format. The version-specific review title is preferred, converted to ASCII, and unsafe separators are replaced with underscores.

Use --clean-older-versions with the default latest-only mode to remove older .vN.md files for the fetched reviews. It retains a numbered file matching the current remote version, refreshes .latest.md, and does not touch unrelated cache files:

python3 skills/miadi-review/scripts/miadi_review.py \
  download-all --clean-older-versions

--all-versions and --clean-older-versions are mutually exclusive.

Every cached Markdown file ends with its full public review URL:

---

## Online Review

[Title of the review](https://miadi-review-service.vercel.app/review/UUID)

Reviews still being generated are recorded in the manifest with no Markdown files and counted as pending. Re-running the command refreshes known .latest.md files from service Markdown, so the URL section is added exactly once. Older numbered files remain untouched unless --clean-older-versions is explicitly supplied.

A human or agent can choose another cache folder:

python3 skills/miadi-review/scripts/miadi_review.py \
  download-all ./cache/miadi-reviews --page-size 50

The manifest contains review IDs, public URLs, source video URLs, latest-version numbers, and relative Markdown paths. It never contains the bearer token.

Where several reviews stand: status

python3 skills/miadi-review/scripts/miadi_review.py status ID1,ID2 ID3

For each review it reads the latest version and returns its title, URL, miadi-review:<uuid> reference, latest_version, has_transcript, the ## headings, and sections: whether the sections that steps 2 and 3 add are present (academic_fields, sources, related_review, internal_usage, definitions). next_step names the first step still owed. A review that cannot be read gets an error entry and the others are still reported.

A section flag only means a ## or ### heading starts with that name. Hand-written reviews use looser names, such as ## Academics or ### related reviews and miadi-chronicle episodes:, so read the headings before calling a step done or missing.

Apply reviews to a job: apply

/miadi-review apply 6c3f477f-…,fcb78dc0-…,09de3362-…
In tmux 'asterion-miadi-circle-threads' I am drafting a prompt … Help me name that and ground it in a foundations/ packet …

The prompt names a job, and the reviews are its sources. The job can be naming a practice, grounding a term in a foundations/ packet, drafting a spec or answering a question. The person also gets the state of each review and the revisions the job suggests.

  1. Run status on the IDs.
  2. Read each review’s latest version (get, or the public /review/<id>/raw). Read its stored transcript when the job needs the video’s exact words.
  3. Do the job. When it is another skill’s work, load that skill and follow it: a foundations/ packet is deep-research-foundations, an episode is chronicle-episode, a GitHub issue is structural-issue-authoring. Cite each claim taken from a review as miadi-review:<uuid> vN, with the review’s timestamp when it gives one. When the prompt points at a tmux session or a file, read it. Type into another session only when the prompt asks for words to land there. Then put them at the end of the person’s draft with tmux send-keys -l, check first that the cursor sits there, never press Enter, and read the pane back. Leaving the words in your reply instead is a missed delivery: on 2026-10-06 the person’s verdict on the first apply run was “nothing sent”.
  4. Count every word limit in the prompt with a script before reporting, and show the counts. “Under 55” means 54 or fewer. The first run reported 55 and 56.
  5. Report in this order: the job’s result, a status table with one row per review (title, version, transcript, steps done), then the revisions as next steps, each with a code (A1, A2, …).

Revisions to look for:

Propose revisions and do not publish them. Each one goes out only after the person approves its exact text, through the publish discipline in miadi-review-academic-fields (dry run, one import, read-back).

When complete, CLI output also includes navigation fields:

{
  "export_directory": "/full/path/to/cache",
  "cd_command": "cd /full/path/to/cache",
  "manifest_path": "/full/path/to/cache/manifest.json",
  "exported_markdown_files": [
    "/full/path/to/cache/Safe_Title.UUID.latest.md"
  ]
}

Use cd_command to navigate directly to the export folder. The absolute file list is printed for both humans and downstream agents; these machine-specific absolute paths are not persisted inside manifest.json.

Read a review without a token

Published reviews are public. To read one review, fetch it directly instead of running the authenticated client:

/review/<id>/raw            Markdown as text/plain (?format=md for text/markdown)
/review/<id>/json           review, selected version, and version list as JSON
/review/<id>/raw?v=2        any of the above, pinned to one version
/review/feed.xml            RSS feed of reviews

Public /review/index, /review/list, and /review/feed.xml also enumerate reviews; do not assume the catalog is private because management/API listing requires authentication. Use the client for authenticated API listing, searching, querying, creating, importing, versioning, deleting, and download-all.

Dialogue adapted from a published review

Read /review/<id>/json for the source video, selected version, model, and structured claims; fetch /raw?v=N when exact Markdown matters. A requested Mia–Ava dialogue is a new adaptation, not the review service’s output, a verbatim video transcript, or words spoken by the video’s participants. Preserve the review URL and selected version as provenance, distinguish the review’s timestamped claims from footage independently checked, and label any later dialogue or Chronicle script accordingly. The service generates and stores reviews; it does not generate, store, or authenticate dialogues.

Amend a published review before an episode

Read the selected public /json and /raw version first. Stage a minimal local Markdown diff against that version (for example, a one- or two-sentence ## Intent naming a direction without claiming Miadi already has an evaluation system); preserve the rest of the review. import-markdown --dry-run checks the source URL and payload without publishing. Obtain approval of the exact amendment before importing once, then read back the new public version and its text. add-version regenerates with AI; it is not the tool for a surgical edit. If the review is still being shaped, defer episode creation even when an episode was requested; one or more review revisions may be needed before the version is ready to carry.

Read the latest version again just before the import. If another seat published a version after your diff, apply the approved edits on top of it, not over it, and apply every one of them. When the other version says the same thing in other words, the approved wording wins. A go covers the recommendations that came with the proposal, so do not turn them into new questions. Reopen an approved edit only when it has become impossible or unsafe, and say which. On 2026-10-08 a fork published v4 of 89f51d13 while another seat’s edits waited for approval. The seat applied five of seven as v5, kept the fork’s wording for the other two, and asked three new questions. The person had to ask what his go had meant, and the rest went out as v7. Grounding: miadi-foundation:delegation-and-adjustable-autonomy (sub-help, transfer of control).

What an ## Intent section holds

## Intent says how we intend to use this review and its video for the next step in the evolution of the Miadi Factory. Write a few lines, in the person’s voice or as “we”. Each line names a use and the next step it leads to. Where something is only wanted, state the current reality plainly next to it.

Earned 2026-10-08 on 89f51d13. v4 put a closing’s title and description under ## Intent, and v7 kept the description. William’s comments on v8: “that is not an intent”, “this is passive description nothing related to what an ‘## Intent’ section would be about”, and “Reality is that we have NO MONEY, no crowd funding and nowhere where we present the miadi-factory to get funding… you are stating what we want with a false claim”. His definition, the same day: an Intent is “about how we intend to use this actual review and that screen walk for the next step in the evolution of the factory”. v12 is the first version written to it, and he accepted it: “we have achieved somewhere we can work with”. The accepted section and the rejected attempts are in examples/intent-acceptable-89f51d13-v12.md and examples/intent-rejected-89f51d13-v4-to-v9.md. Read both before writing an Intent.

Something the audience can install

A screenwalk sometimes shows work on something a viewer can install, often as a detour from what was planned. Examples are a plugin from jgwill/miadi-orchestration-kit (public) or a published package. A revision then gives the review one short section, ## Try It: <name>. It goes last, or just before ## Sources when the review has one, so a person reads the review before the install steps. It holds three things:

claude plugin marketplace add jgwill/miadi-orchestration-kit
claude plugin install <plugin>@miadi-orchestration-kit

Check the plugin name against the kit’s .claude-plugin/marketplace.json before writing it.

Earned 2026-10-08 with the Episode 140 screenwalk (89f51d13). William could not work with Mia on the trading platform while her phone page cut his takes, so the session stopped and upgraded the mia-episode-companion plugin live. He named that unplanned upgrade as what a viewer can take from the video.

A review inside the chronicle

A review is also a reusable record in the Miadi chronicle, not only a page on this service. Since jgwill/Miadi#682 (2026-09-24) it has these names, and this skill’s client writes none of them:

name what it is
miadi-review:<uuid> the portable reference an episode cites (references: or reviews: in episode.yaml)
review:<uuid> the review’s one node on the chronicle wheel, type: knowledge, metadata.kind: miadi_review, with public_url and latest_version
chronicle:<episode> → review:<uuid> one edge per episode; its relationship type says what that episode uses the review for
talking_circle with subject_id: review:<uuid> a ceremony held about the review, in a circle of people

Put an approved review version into an episode, or begin an episode from one. That write belongs to Miadi’s episode door, owned by the chronicle-episode skill: POST /api/chronicle/episodes/<ref>/reviews {review, relation?} or POST /api/chronicle/episodes {review}. After the review version is approved, published, and read back, hand its URL with ?v=N to the episode door as a separate act and report both results. The door records the review and relates it on the wheel; a talking circle opens only when a person is authorized to hold it. A writer token alone may leave the ceremony owed—do not report it as opened without a read-back. Never create the node or the edge by hand; Episodes 339 to 345 did, and the door now keeps those edges as they are.

Find where a review is used (read-only, no token; the wheel is $MIADI_CHRONICLE_MW_URL):

R=review:<uuid>
curl -s "$MIADI_CHRONICLE_MW_URL/api/edges?limit=all" | jq --arg r "$R" '[.[] | select(.to_id == $r) | {episode: .from_id, relation: .relationship_type}]'
curl -s "$MIADI_CHRONICLE_MW_URL/api/ceremonies?subject_id=$R&limit=all" | jq '[.ceremonies[] | {id, episode_path, circle_id}]'

Ask for ?limit=all: a bare edge list stops at 100 rows and silently leaves most episodes out. Inside Miadi, GET /api/chronicle/episodes/<ref>/reviews lists one episode’s reviews with their circles.

Versions. An episode records the version it used. add-version publishes a newer one and leaves that record alone; the episode room then shows “vN published” next to the version it used. Say so when you add a version to a review that episodes hold.

Phase 2: enrich a review

Once a review is published, two companion skills in this folder enrich it. Each group of changes becomes its own version:

Run them in that order (jgwill/Miadi#692).

Response protocol

  1. Parse the JSON response.
  2. For creation/import, require version >= 1 and public_url_verified: true before reporting success.
  3. Report id, url, and version only after those completion checks pass.
  4. For AI creation, report reused when present; if true, say clearly that no new review was generated.
  5. A record with version 0, no versions, or a public 404 is incomplete—not a successful review. A failed AI generation deletes its new row, so a version-0 record is either still generating or predates that rollback.
  6. AI creation retries once by default after a timeout or incomplete response; use --attempts 1..3 to control this. Direct Markdown import is submitted once to avoid duplicate manual versions.
  7. On 401, report that MIADI_REVIEW_TOKEN must be refreshed in the process environment or configured credential file; never ask the operator to paste it into chat.
  8. Preserve prior versions unless the user explicitly requests permanent deletion. For deletion, require exact review-ID confirmation and report versions_deleted.
  9. After creation or import, also give the chronicle reference miadi-review:<uuid>, so the review can be cited in an episode.

Safety boundary