Kiroku Tutorials And Flows

This guide teaches Kiroku by workflow. It is written for someone trying to understand how the product behaves in real use, not just where buttons are located.

Use this with the Feature Tour and User Guide:

• Feature Tour: product map and feature list.
• User Guide: control-by-control reference.
• Tutorials And Flows: how the parts work together.

For implementation terminology, see Queue Product Model. The short version is: Queue is the canonical user-facing concept, queue items are global while unscheduled, and scheduling places an item into the currently selected workspace.

The Mental Model

Kiroku has five core states:

Most productivity tools stop at capture or calendar. Kiroku joins both. The queue catches raw work, smart scheduling proposes safe slots, and Daily Workflow prevents missed work from vanishing.

Tutorial 1: Plan A Real Week From A Blank Planner

Goal: build a week that is realistic, visible, and easy to adjust.

Step 1: Choose The Shape Of The Week

Open Settings > Days.

Decide:

Why this matters: smart scheduling only searches visible days and visible hours. If you hide weekends, Plan this week will not place work there.

Step 2: Add Fixed Commitments First

Create blocks for meetings, appointments, school pickup, workouts, or hard deadlines.

Use fixed commitments for anything with a real time. Kiroku treats those blocks as occupied when suggesting queue slots.

Step 3: Add Flexible Work To The Queue

Open the queue and add items like:

• Write launch checklist.
• Review contract.
• Prepare Q3 plan.
• Process receipts.
• Follow up with customer.

Do not schedule everything manually yet. Let the queue hold items until the fixed commitments are visible.

Step 4: Use Smart Scheduling

Open the queue.

For each item:

Expected result: the item disappears from the queue only after it becomes a real task on a visible day.

Step 5: Read The Daily Workflow Strip

The daily workflow strip shows whether the selected day is within capacity. If it says the day is over capacity, do not ignore it. Use Start Day or End Day to defer work instead of manually hunting through the grid.

Tutorial 2: Understand Smart Scheduling

Smart scheduling does not call AI. It does not classify your task text. It does not send private calendar content to a model.

It is a deterministic slot-finding algorithm.

Inputs

Plan Today Flow

Queue item selected
  -> Is smart scheduling enabled?
  -> Is queue slot hinting enabled?
  -> Is selected day visible?
  -> Is selected day today or later?
  -> Search open slots inside visible hours
  -> If a slot fits, enable Plan today
  -> If no slot fits, disable Plan today

Plan This Week Flow

Queue item selected
  -> Build candidate days from the displayed week
  -> Remove hidden days
  -> Remove past days
  -> For today, remove time before now
  -> Search each day for the first fitting slot
  -> Show the first usable suggestion

Example

Assume today is Saturday and your visible days are Monday through Friday.

That is why the queue item should stay in the queue instead of disappearing.

Smart Scheduling Settings

Open Settings > Smart Scheduling.

Troubleshooting

Tutorial 3: Capture Work Without Opening The Planner

Kiroku supports multiple intake routes, but they all converge into the queue. That is the important part: no matter how an item arrives, you triage it the same way.

Capture Routes

Quick Capture

Use Quick Capture when you are already in Kiroku and need to record something quickly.

Flow:

Click capture
  -> Choose queue item, task, alert, or journal
  -> Enter title
  -> Add details if needed
  -> Submit
  -> Item lands in queue or schedule

Use details for context you do not want to lose. When the item becomes a task, those details become task notes.

Email Intake

Open Settings > Integrations and copy the user's inbound capture email address.

Flow:

Forward email to inbound capture address
  -> Inbound mail provider posts to Kiroku
  -> Kiroku resolves the alias to a user
  -> Message is stored in hosted capture feed
  -> Client opens or syncs
  -> Message appears in queue

Routing rule:

Retention rule: if the user does not open the app for days, hosted capture items wait until the admin-configured retention window expires.

For Postmark inbound, point the webhook at https://app.kirokulab.com/api/capture/postmark. Postmark webhook auth should use Basic Auth: any username, and a password matching the production webhook secret configured in Kiroku.

Browser Extension

Use the extension when the useful object is a web page.

It can capture:

• Page title.
• URL.
• Selected text.
• Screenshot.
• Source metadata.

Use the browser extension page for Chrome and Edge setup. Settings > Integrations shows the

user-specific extension capture key.

The extension does not need a workspace selector. Captures go to the global queue and are triaged in Kiroku. If the browser retries the same capture, Kiroku treats the duplicate idempotency key as an already accepted capture instead of creating another queue item.

Bookmarklet

Use the bookmarklet when browser policy blocks extensions.

Use the bookmarklet page for browser-specific setup. Settings > Integrations shows the

bookmarklet generated for the current Kiroku environment.

The bookmarklet is less capable than the extension, but it is easy to deploy.

Tutorial 4: Run Start Day

Start Day is for deciding what today is allowed to become.

When To Use It

Use Start Day:

• First thing in the morning.
• Before a deep work block.
• After a weekend or missed day.
• When the queue has grown.
• When the calendar looks full but you are not sure why.

What Each Stage Means

Recommended Start Day Routine

1. Open Start Day.
2. Look at carryover first.
3. Delete anything that no longer matters.
4. Use smart suggestions for queue items that belong today.
5. Watch capacity.
6. If over capacity, defer suggested work.
7. Confirm the day.

What Not To Do

Do not drag everything manually while ignoring the queue. That skips the most useful part of Kiroku: clear decisions about work before it becomes a task block.

Tutorial 5: Run End Day

End Day closes the loop.

Flow:

Open End Day
  -> Review open work
  -> Mark completed work
  -> Carry unfinished work forward
  -> Convert unresolved work back to queue if timing is unknown
  -> Write reflection
  -> Finish session

What To Carry Forward

Carry forward an item when:

• It is still important.
• It has a likely next-day slot.
• It should remain visible as planned work.

Move back to queue when:

• You do not know when it belongs.
• It needs more information.
• It should not consume tomorrow's capacity yet.

Delete when:

• It is obsolete.
• It was noise.
• It belongs in another system.

Tutorial 6: Use The Queue As The Source Of Truth

The queue is not a junk drawer. It is the staging area for work that has not earned a place on the calendar.

Queue Item Anatomy

Triage Decision Tree

Does this still matter?
  -> No: delete it.
  -> Yes: does it need a real time?
       -> Yes: Pick time.
       -> No: can it fit today?
            -> Yes: Plan today.
            -> No: can it fit this visible week?
                 -> Yes: Plan this week.
                 -> No: leave queued or defer.

Practical Rule

If the item is not actionable, rewrite it before scheduling it.

Weak item:

Vendor

Strong item:

Email vendor about renewal price increase

Smart scheduling can place time, but it cannot make vague work clear.

Tutorial 7: Use Command Palette For Keyboard Planning

Open Ctrl + K and type a natural phrase.

Examples:

How to think about it:

Text with time -> scheduled task
Text without time -> queue item
Text with #type -> matching task type
Alert command -> alert

Use command palette for fast entry. Use the queue when you need to triage many items visually.

Tutorial 8: Review Time And Calendar History

Time Tracking answers "what did I spend time on?"

Use it weekly to review:

• Total scheduled time.
• Breakdown by task type.
• Daily workload shape.
• Overcommit patterns.
• Whether your planned week matches reality.

Calendar View answers "where is everything over the month?"

Use it to:

• Jump to a date.
• Review month density.
• Spot holiday collisions.
• Inspect weeks without scrolling.

Tutorial 9: Configure A Workspace For A Real Role

Workspaces are independent planning contexts. Use them when different work should not share task types, colors, templates, or day settings.

Example: Product Manager Workspace

Example: Personal Workspace

Workspace Rule

If a category needs a different calendar shape, make it a workspace. If it only needs a different color, make it a task type.

Tutorial 10: Configure External Capture For Hosted Kiroku

External capture is made of three layers:

Email Intake Checklist

1. Configure the inbound email domain, such as intake.example.com.
2. Configure the mail provider inbound webhook to post to https://app.kirokulab.com/api/capture/postmark.
3. In Postmark, use Basic Auth with any username and the Kiroku webhook secret as the password.
4. Make sure each user has a generated inbound capture alias.
5. Open Settings > Integrations.
6. Copy the inbound capture email address.
7. Forward a test message.
8. Open Queue.
9. Confirm the message appears with source Email.
10. Open task details after scheduling and confirm the full body appears in notes.

Extension Capture Checklist

1. Open the browser extension page.
2. Install or load the Chrome/Edge package.
3. Open Settings > Integrations.
4. Copy the Extension capture key.
5. Paste the key into extension options.
6. Capture a page.
7. Confirm the extension popup closes after the capture is accepted.
8. Open Kiroku Queue.
9. Confirm title, URL, selected text, and screenshot.
10. Schedule the item and open task notes.

Debugging Checklist

Tutorial 11: Understand Sync And Offline Behavior

Kiroku keeps the UI responsive by writing locally first. Hosted sync then moves state between devices and server APIs.

Local First

In the planner, changes feel immediate because the browser writes to IndexedDB. This includes tasks, notes, global queue items, settings, workspaces, and journal entries.

Hosted Sync

When authenticated, the app syncs planner state to the hosted backend.

Sync handles:

• Uploading local planner state.
• Downloading server state.
• Server-sent update events.
• Polling fallback.
• Conflict detection.

External Capture Queue

Email and extension captures can arrive while the client is closed. Those items live in hosted capture storage until pickup or expiry.

Admin capture settings determine retention. For example, a 3-day retention policy means a user who does not open the app for more than 3 days may miss old unpicked captures.

Tutorial 12: Admin And Enterprise Boundaries

Admin features fall into two groups:

Enterprise controls should only appear when:

1. The enterprise image is built.
2. The runtime is running in enterprise mode.
3. The user's feature flags permit the function.

This keeps the regular hosted app simpler and prevents enterprise-only actions from appearing in the wrong deployment.

Feature Recipes

Recipe: Clear A Busy Queue In Ten Minutes

1. Open Queue.
2. Filter to Email.
3. Delete obsolete messages.
4. Use Plan today for urgent messages.
5. Use Plan this week for useful but flexible messages.
6. Leave unclear items queued.
7. Run Start Day.

Recipe: Recover An Overloaded Day

1. Open Start Day.
2. Look for an over-capacity warning.
3. Review suggested deferrals.
4. Click defer suggestion when it matches reality.
5. Recheck capacity.
6. Confirm the day.

Recipe: Save A Web Page For Later

1. Select useful text on the page.
2. Click the Kiroku extension.
3. Include screenshot if the visual state matters.
4. Capture.
5. Later, open Queue.
6. Use Plan this week.
7. Open task notes to review URL, selection, and screenshot.

Recipe: Build A Repeatable Meeting Day

1. Create the meeting day once.
2. Lock any fixed tasks whose schedule, type, and status should not change.
3. Right-click the day header.
4. Save as template.
5. Apply it to the next matching date.
6. Adjust only the variable tasks.

Recipe: Weekly Review

1. Open Time Tracking.
2. Select this week.
3. Review time by task type.
4. Open Calendar View.
5. Look at next week.
6. Add fixed commitments.
7. Open Queue.
8. Plan high-value items into open slots.

How The Major Features Fit Together

What To Test After Changing These Features

Use this list when verifying changes.

Smart Scheduling

• Queue item shows a suggestion when a visible slot exists.
• Plan today creates a task on the selected visible day.
• Plan this week skips hidden days.
• Plan this week skips past days.
• Full days disable suggestions.
• Turning off Queue slot hints removes planning buttons.

Capture

• Manual queue item persists after reload.
• Email capture appears in queue.
• Extension capture appears in queue.
• Details become task notes after scheduling.
• Images in notes open correctly.
• Extension popup closes after accepted capture.
• Duplicate extension capture keys do not create duplicate queue items.
• Deleting a queue item is permanent.

Tasks And Templates

• Locked task blocks schedule, type, status, and alert/task-mode edits.
• Locked task cannot be moved or resized by drag.
• Saving a day template preserves each task's lock state, status, and planning fields.
• Applying a day template recreates locked tasks as locked and copies estimates, actuals, deadlines, priority, and scheduling constraints.

Daily Workflow

• Start Day opens from toolbar.
• Carryover and queue groups show correct counts.
• Capacity warning appears when over daily capacity.
• Suggested deferral changes the planner.
• End Day can carry unresolved work forward.

Sync

• Local changes persist in IndexedDB.
• Authenticated changes upload.
• Second device receives task, queue, template, task type opacity, status/lock, note/image, journal, and planning-field changes.
• External captures wait for pickup.
• Retention removes old unpicked captures.

Admin And Enterprise

• Hosted admin pages load in hosted mode.
• Enterprise-only controls are hidden in non-enterprise mode.
• Enterprise controls appear in enterprise build and enterprise runtime.
• The admin Support page searches by user identity and shows sanitized account, sync, capture alias, and capture-event diagnostics for troubleshooting.
• Capture retention settings affect pickup behavior.

Glossary