@agentshouse/skills 0.0.0-stage → 0.1.0-c056ffcd3832e

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/README.md +32 -2
  2. package/agent-instructions.json +9 -0
  3. package/dist/index.d.ts +21 -0
  4. package/dist/index.js +61 -0
  5. package/guide/apps/build.md +14 -0
  6. package/guide/apps/chat.md +23 -0
  7. package/guide/apps/client.md +21 -0
  8. package/guide/apps/content-safety.md +18 -0
  9. package/guide/apps/data.md +13 -0
  10. package/guide/apps/example-function.md +67 -0
  11. package/guide/apps/example-tasks-2.md +101 -0
  12. package/guide/apps/example-tasks-3.md +52 -0
  13. package/guide/apps/example-tasks.md +75 -0
  14. package/guide/apps/functions.md +13 -0
  15. package/guide/apps/local-first.md +16 -0
  16. package/guide/apps/local-query-results.md +27 -0
  17. package/guide/apps/local-query.md +44 -0
  18. package/guide/apps/local-search.md +35 -0
  19. package/guide/apps/page.md +13 -0
  20. package/guide/apps/room-drafts.md +45 -0
  21. package/guide/apps/runtime-api.md +43 -0
  22. package/guide/apps/runtime-files.md +55 -0
  23. package/guide/apps/runtime-refusals.md +19 -0
  24. package/guide/apps/runtime.md +14 -0
  25. package/guide/apps/start.md +12 -0
  26. package/guide/apps/verify.md +16 -0
  27. package/guide/get-started.md +11 -0
  28. package/guide/index.md +12 -0
  29. package/guide/owner-rules.md +40 -0
  30. package/guide/reference/access-level.md +9 -0
  31. package/guide/reference/app-manifest.md +12 -0
  32. package/guide/reference/routine.md +15 -0
  33. package/guide/reference/schema.md +28 -0
  34. package/guide/reference/triggers.md +17 -0
  35. package/guide/routines/work-on-ticket.md +15 -0
  36. package/guide/sites/build.md +18 -0
  37. package/guide/sites/entry-data-contract.md +25 -0
  38. package/guide/sites/runtime.md +19 -0
  39. package/guide/skills/build-app.md +25 -0
  40. package/guide/skills/house-onboarding.md +29 -0
  41. package/guide/skills/prototype-app.md +40 -0
  42. package/guide/skills/wizard.md +22 -0
  43. package/owner-rules-earlier.json +9 -0
  44. package/package.json +31 -4
  45. package/set/ask-matt/LICENSE +21 -0
  46. package/set/ask-matt/PHASE-BOUNDARIES.md +55 -0
  47. package/set/ask-matt/SKILL.md +97 -0
  48. package/set/ask-matt/agents/openai.yaml +5 -0
  49. package/set/code-review/LICENSE +21 -0
  50. package/set/code-review/SKILL.md +89 -0
  51. package/set/code-review/agents/openai.yaml +3 -0
  52. package/set/codebase-design/DEEPENING.md +37 -0
  53. package/set/codebase-design/DESIGN-IT-TWICE.md +44 -0
  54. package/set/codebase-design/LICENSE +21 -0
  55. package/set/codebase-design/SKILL.md +114 -0
  56. package/set/codebase-design/agents/openai.yaml +3 -0
  57. package/set/diagnosing-bugs/LICENSE +21 -0
  58. package/set/diagnosing-bugs/SKILL.md +138 -0
  59. package/set/diagnosing-bugs/agents/openai.yaml +3 -0
  60. package/set/diagnosing-bugs/scripts/hitl-loop.template.sh +44 -0
  61. package/set/domain-modeling/ADR-FORMAT.md +47 -0
  62. package/set/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  63. package/set/domain-modeling/LICENSE +21 -0
  64. package/set/domain-modeling/SKILL.md +74 -0
  65. package/set/domain-modeling/agents/openai.yaml +3 -0
  66. package/set/grill-me/LICENSE +21 -0
  67. package/set/grill-me/SKILL.md +7 -0
  68. package/set/grill-me/agents/openai.yaml +5 -0
  69. package/set/grill-with-docs/LICENSE +21 -0
  70. package/set/grill-with-docs/SKILL.md +7 -0
  71. package/set/grill-with-docs/agents/openai.yaml +5 -0
  72. package/set/grilling/LICENSE +21 -0
  73. package/set/grilling/SKILL.md +30 -0
  74. package/set/grilling/agents/openai.yaml +3 -0
  75. package/set/handoff/LICENSE +21 -0
  76. package/set/handoff/SKILL.md +16 -0
  77. package/set/handoff/agents/openai.yaml +5 -0
  78. package/set/implement/LICENSE +21 -0
  79. package/set/implement/SKILL.md +17 -0
  80. package/set/implement/agents/openai.yaml +5 -0
  81. package/set/implement-spec/LICENSE +21 -0
  82. package/set/implement-spec/SKILL.md +40 -0
  83. package/set/implement-spec/agents/openai.yaml +5 -0
  84. package/set/improve-codebase-architecture/HTML-REPORT.md +123 -0
  85. package/set/improve-codebase-architecture/LICENSE +21 -0
  86. package/set/improve-codebase-architecture/SKILL.md +71 -0
  87. package/set/improve-codebase-architecture/agents/openai.yaml +5 -0
  88. package/set/pr/CREDITS.md +3 -0
  89. package/set/pr/LICENSE +21 -0
  90. package/set/pr/SKILL.md +170 -0
  91. package/set/pr/agents/openai.yaml +3 -0
  92. package/set/prototype/LICENSE +21 -0
  93. package/set/prototype/LOGIC.md +67 -0
  94. package/set/prototype/SKILL.md +26 -0
  95. package/set/prototype/UI.md +112 -0
  96. package/set/prototype/agents/openai.yaml +3 -0
  97. package/set/research/LICENSE +21 -0
  98. package/set/research/SKILL.md +12 -0
  99. package/set/research/agents/openai.yaml +3 -0
  100. package/set/retro/LICENSE +21 -0
  101. package/set/retro/SKILL.md +44 -0
  102. package/set/retro/agents/openai.yaml +5 -0
  103. package/set/tdd/LICENSE +21 -0
  104. package/set/tdd/SKILL.md +38 -0
  105. package/set/tdd/agents/openai.yaml +3 -0
  106. package/set/tdd/mocking.md +59 -0
  107. package/set/tdd/tests.md +77 -0
  108. package/set/teach/GLOSSARY-FORMAT.md +35 -0
  109. package/set/teach/LEARNING-RECORD-FORMAT.md +46 -0
  110. package/set/teach/LICENSE +21 -0
  111. package/set/teach/MISSION-FORMAT.md +31 -0
  112. package/set/teach/RESOURCES-FORMAT.md +32 -0
  113. package/set/teach/SKILL.md +140 -0
  114. package/set/teach/agents/openai.yaml +5 -0
  115. package/set/to-questionnaire/LICENSE +21 -0
  116. package/set/to-questionnaire/SKILL.md +54 -0
  117. package/set/to-questionnaire/agents/openai.yaml +5 -0
  118. package/set/to-spec/LICENSE +21 -0
  119. package/set/to-spec/SKILL.md +75 -0
  120. package/set/to-spec/agents/openai.yaml +5 -0
  121. package/set/to-tickets/LICENSE +21 -0
  122. package/set/to-tickets/SKILL.md +105 -0
  123. package/set/to-tickets/agents/openai.yaml +5 -0
  124. package/set/triage/AGENT-BRIEF.md +207 -0
  125. package/set/triage/LICENSE +21 -0
  126. package/set/triage/OUT-OF-SCOPE.md +105 -0
  127. package/set/triage/SKILL.md +112 -0
  128. package/set/triage/agents/openai.yaml +5 -0
  129. package/set/wait-what/LICENSE +21 -0
  130. package/set/wait-what/SKILL.md +7 -0
  131. package/set/wait-what/agents/openai.yaml +5 -0
  132. package/set/wayfinder/LICENSE +21 -0
  133. package/set/wayfinder/SKILL.md +128 -0
  134. package/set/wayfinder/agents/openai.yaml +5 -0
  135. package/set/writing-for-agents/LICENSE +21 -0
  136. package/set/writing-for-agents/SKILL-MECHANICS.md +22 -0
  137. package/set/writing-for-agents/SKILL.md +81 -0
  138. package/set/writing-for-agents/agents/openai.yaml +3 -0
  139. package/upstream.json +32 -0
@@ -0,0 +1,35 @@
1
+ # Local Search rules
2
+
3
+ How `search` finds Documents and messages by words on the device.
4
+
5
+ `search({ text, documents, collection, conversations, limit, after, total })` answers
6
+ once, by words, from the full-text index the browser keeps with its local state, so it
7
+ answers at once after a reload. There is no observed search.
8
+
9
+ - **Declaration.** Only an App whose release declares Local Search searches; any other
10
+ App's `search` answers the never retryable `undeclared` refusal `search-undeclared`, its
11
+ `fields` naming `local_search`.
12
+ - **What is found.** A Document by its field values, its sections' headings and text, its
13
+ preamble and its Path, and a message by its text, never a frontmatter key, a Room Draft,
14
+ a chat draft or a running turn's parts. Any word found ranks a hit, more found rank it
15
+ higher, and adjacent words higher still; case and the marks of Latin, Greek and
16
+ Cyrillic letters fold, English word forms stem, the last word also matches as the start
17
+ of a word unless the text ends with a space, and Chinese, Japanese, Korean and Thai text
18
+ matches by character pairs. There is no typo tolerance and no operator syntax.
19
+ - **Narrowing.** `documents` is a Local Query filter, and `collection: true` leaves out
20
+ what each Room's `typedSelection` roots hold; `conversations` names conversations. All
21
+ apply before `limit`, which bounds each list, at most 1,000 whatever a search names. A
22
+ complete answer it cuts short names `next`, which `after` takes for the next window of
23
+ both lists. `total: true` adds `total`, each list's count. A word in very many Documents
24
+ ranks among a bounded set of them, the Documents of a rarer word of the search always
25
+ among them.
26
+ - **Results.** `{ documents, messages, coverage }`, or the same with `pending` naming each
27
+ Room the search still waits for: show its hits, ask again, and never read pending as no
28
+ hits. `coverage` names the Rooms and conversations searched. Each list is ranked by
29
+ `score`, comparable only within it; ties come by `room`, then `path`, or by
30
+ `conversation`, then `identity`. A Document hit names its `room`, `path` and `type`, a
31
+ message hit its `conversation` and `identity`; `matches` maps each word of the search
32
+ to the parts it was found in: `fields`, `sections`, `preamble`, `path` or `text`. A hit
33
+ whose words were found carries `snippet: { part, text, at }`: the part's text around
34
+ the first word found, at most 80 characters on either side, and `at` that word's start
35
+ and end in `text`. Mark the words you show. A bad filter fails as a query does.
@@ -0,0 +1,13 @@
1
+ # An App's page
2
+
3
+ What an App's page draws and how it behaves in the browser.
4
+
5
+ - The App draws everything; House draws nothing around it. Set the tab's title with `bridge.setTab({ title })`.
6
+ - The address bar is the shell's, not your page's: read your place from `bridge.address()` and `bridge.onAddress`, and move with `bridge.push` or `bridge.replace`, so Back, Forward, reload and a shared link keep it; a push to the address already shown replaces it, so a double click adds no history entry. After an act that ends what the page shows, and when a dialog closes, `bridge.replace` the next address; a replace with the address this page was opened from goes back to it, so Back returns to where the person came from. Keep the open item, tab, filter and search in the address. Addresses under `/render` and `/info` are House's.
7
+ - Files: take one in with `binaryFile.attach` the moment it is chosen and keep the Path it answers, hand one out with `binaryFile.download`, and show an image or video in `<room-media>` naming its width and height, so nothing waits for media and nothing moves when it arrives; never read a file whole to show or download it ([files](apps/runtime-files)).
8
+ - Mobile first: lay out from 360 pixels wide up, with no action behind hover alone.
9
+ - Every control works from the keyboard, with visible focus and a label.
10
+ - An empty list says what it will hold and invites the first document.
11
+ - Long names truncate with an ellipsis and show in full on hover.
12
+ - The element is the link: a row, card or name opens its item; no "Open" buttons.
13
+ - Offer installation yourself: `bridge.install()` from a click shows the browser's prompt, or answers `manual` where you show how.
@@ -0,0 +1,45 @@
1
+ # Room Draft, Save, and outcome rules
2
+
3
+ How App code writes a Room Draft, saves it and learns what became of each change.
4
+
5
+ The MD Runtime owns one durable Room Draft per Room and Path, shared by every App and tab
6
+ across reloads; a Room the Provider reports lost takes its Room Drafts and queue with it.
7
+ Write one with `roomDraft.write(room, path, revision, parts)`, naming the revision you read
8
+ or `null`, and every part it now changes: fields, sections and the preamble, or the whole
9
+ Markdown, a creation, a move, into another Room when it names `room`, or a removal. A new
10
+ part names its base, the value you showed when it was opened, a field's as `{ value }` or
11
+ `null` for no such field, and keeps its first base; a binary Path entry's move or removal
12
+ takes `null`. A write or discard from an older revision is refused as `stale` with the
13
+ current Room Draft.
14
+
15
+ Save takes one Room and the Room Drafts of it to save, each with its revision, validates
16
+ locally, and on success appends one Change Batch to that Room's queue and removes those Room
17
+ Drafts. Refused as `stale`, `changed-underneath` naming each part whose base no longer
18
+ matches the visible state, or a local validation rule, it creates nothing and leaves every
19
+ Room Draft. A directory move or removal is that part on each Document and binary Path entry
20
+ beneath it, saved together; moves into another Room, saved alone, are one Change Batch in
21
+ both Rooms' queues. `saveParts(room, [{ path, parts }])` saves parts, each Path once and
22
+ each new part with its base, the same way but writes no Room Draft: one held at a saved Path
23
+ stays, one at a moved Path moves with it to a destination that holds none. Never save by
24
+ writing back a Room Draft read before.
25
+
26
+ Outcomes follow the Provider's answer. An Accepted Change Batch stays in the queue, drawn
27
+ over the confirmed layer, until that layer reaches the Room Version it was accepted at.
28
+ Conflicted and Rejected, an expired operation, and a change that no longer applies each
29
+ leave the queue and return as Room Drafts on their Documents, marked with why: the
30
+ Provider's structured refusal code and fields as returned, not known to have applied, or
31
+ withdrawn locally. The rest of the queue keeps synchronizing, and Sync Status requires
32
+ attention until each returned Room Draft is saved or discarded. `observe('queue', room)`
33
+ shows each Pending Change Batch, which keeps no outcome once it leaves. Transport failure,
34
+ Provider unavailability and a refusal marked retryable, until the reset it names, keep
35
+ work Pending; the MD Runtime retries the same Change Batch identity and payload, never
36
+ infers an outcome from transport uncertainty, and never combines, reorders, or rebases.
37
+
38
+ `observe('service-mode')` answers the Provider's Service Mode, `open` or `write-halted`. While writes
39
+ are halted, Save succeeds, its Change Batch waits unsent and the queue is submitted in order once writes
40
+ reopen; an Action is never held, and one the halt refuses returns that refusal: show the Provider as
41
+ read-only instead of retrying. `observe('readiness')` tells whether code and bound Rooms are held
42
+ locally (`ready`), each Room's state, each refused Room's file and rule, the persistence answer, `space`
43
+ (`full` once the device's storage refused a write, Save and messages refusing as `durable-write` until
44
+ `retry()` or a later test write finds space, or once the origin refused a newer release), and the
45
+ `installation`'s Rooms, parts, bytes, `step` and `paused`.
@@ -0,0 +1,43 @@
1
+ # The MD Runtime API
2
+
3
+ What App code reaches through the runtime's client: its surfaces, its reach, observations, Agents and conversations.
4
+
5
+ App code reaches the MD Runtime through the remote client. The surfaces are Rooms, Query,
6
+ Search, Observe, Types, Room Draft, Save, History, Resolve, binary files, Call,
7
+ Reached, Log, the reported persistence answer, reauthorization, conversation, the chat
8
+ draft, and Presentation State. Sync Status, readiness, the Service Mode, the storage-loss
9
+ statement, the deployment facts and the signed-in member are observations only.
10
+
11
+ The host attaches each port with its reach, and every member and observation answers
12
+ within it: a Room outside it answers as one the replica does not hold, Rooms lists only
13
+ the Rooms reached whole, a Room reached for single Documents shows only them and their
14
+ models' Types, and without conversations the conversation members, chat draft and
15
+ observation hold none. A changed reach reaches every open observation as its new value.
16
+
17
+ Every `observe` resolves, once its first value arrived, to a handle: `current()` is the
18
+ latest complete value, `subscribe(listener)` hears each later value whole and returns its
19
+ unsubscribe, and `close()` ends it. Closing the port ends every handle and rejects every
20
+ pending call and observation; a reconnected client observes again.
21
+
22
+ `observe('agents')` answers every Agent a new conversation can go to, each `{ identity,
23
+ name }`, a retired one left out: online every Agent of the User, with a conversation yet or
24
+ not, offline every Agent a conversation names. Each conversation the Provider lists is held
25
+ complete in the browser. `conversation.list()` and `observe('conversations')` answer each
26
+ with its Agent's identity and name, its name, created and finished times, last outcome,
27
+ live `state` (`asking` while a question waits, `working` while a turn runs, else `idle`)
28
+ and `started`, when the running turn began, or `null`. `observe('conversation', id, {
29
+ limit, total: true })` holds its latest `limit` messages, at most 1,000, oldest first,
30
+ `total` their count, and `next` while older ones exist, which `after` takes, there or in
31
+ `conversation.read(id, { limit, after })`, for the window before; its chat draft; and,
32
+ only in memory, what the Provider streams whether or not anything views it: the running
33
+ `turn` with its parts and its context in use and window, which the message accepted under
34
+ the turn's id replaces, the open questions, the process state, and the CLI's commands and
35
+ options, none stored or searchable. `chatDraft.write` and `chatDraft.discard` keep what
36
+ the App Creator composes, and `chatDraft.prepend(conversation, draft)` puts a returned
37
+ message ahead of it as it stands. Sending it is a Provider Action that needs the Provider
38
+ reachable and is never queued. A new conversation's chat draft is keyed `new:<Agent
39
+ identity>`: no conversation list removes it, a retired Agent's goes, and the first answer
40
+ to `conversation.create({ agent_id, operation_id })` moves it to the created conversation,
41
+ where `conversation.send(conversation)` sends it; a replay of that create moves nothing.
42
+
43
+ Next: [Presentation State, binary files and the network](apps/runtime-files)
@@ -0,0 +1,55 @@
1
+ # Presentation State, binary files and the network
2
+
3
+ How the MD Runtime API keeps Presentation State and binary files, and which members reach the network.
4
+
5
+ Presentation State is one value per App, kept in the browser and shared by its tabs:
6
+ `presentation.read()` answers it, `null` before anything is kept,
7
+ `observe('presentation')` hears it whole, `presentation.write(value)` replaces it whole,
8
+ and `presentation.edit(members)` sets each member named, or removes one named `null`, in
9
+ the state as it stands, so tabs changing different members never lose each other's change:
10
+ never write back a value read before. Each rejects when the browser does not keep the
11
+ change, and no tab sees it then.
12
+
13
+ A binary file at a Path is a binary Path entry. Query lists it by `path`, and History each
14
+ of its revisions, with its `binaryFile` record and never its bytes: `{ state: 'accepted',
15
+ revision, path, byteLength, mediaType, sha256 }`, or `{ state: 'pending', localId, path,
16
+ byteLength, mediaType, sha256 }` while an upload the panel saved waits for the Provider.
17
+ Text names a file only by a link to its Path, and a field by a `reference: attachment`. Move
18
+ or remove one as a Document, its bytes following.
19
+
20
+ - `binaryFile.attach(room, file)` writes the `File` into the Room at
21
+ `attachments/<YYYY-MM-DD>/<name>`, a free name, and answers `{ kind: 'attached', path }`,
22
+ the Room Path to link, download, show and read at once, `{ kind: 'offline' }`, or a
23
+ refusal or failure. A Room Draft write
24
+ or Save carrying a `file` part is refused as `attach-required`.
25
+ - `binaryFile.download(room, path, revision?)`, called from a click, hands the browser its
26
+ own download of the Provider's address at once, or of a pending file's saved bytes, and
27
+ answers `{ kind: 'started' }`, `blocked` where the browser refused the tab an `.html`
28
+ page opens in, or a refusal or failure.
29
+ - `<room-media room path width height alt>` draws an image, video or audio file of the
30
+ Room. It reserves the box `width` and `height` set, in the file's own pixels, or a 16:9
31
+ one, before any byte; asks for the file only as it nears the view; draws a file the
32
+ browser keeps from its bytes, offline too, and reads and keeps an image; plays a video
33
+ or audio file from the Provider's address loading only its metadata; asks again when a
34
+ shown file's address lapses; asks again while the file cannot be shown yet, such as
35
+ while the Room does not hold it or House did not answer, until House refuses it for
36
+ good; and shows its children where the file cannot be read.
37
+ - `binaryFile.read(room, path, revision?)` answers `{ kind: 'binary', stream, byteLength,
38
+ mediaType }`, the bytes a `ReadableStream` of parts of at most a mebibyte, which the
39
+ browser keeps for later reads, offline too.
40
+
41
+ Rooms, Query, Search, Observe, Types, Room Draft, Save, and Reached never touch the
42
+ network; History, a binary file's attach and download, a file shown or read that the
43
+ browser does not keep, and Call go to the Provider through the Adapter.
44
+ Call takes the Action names the Adapter declares, any other answering `undeclared`. A Call
45
+ result whose effect the Provider places in a Room carries `at`, that Room and Room
46
+ Version: `reached(room, roomVersion)` answers whether the Room's confirmed state has
47
+ reached it, which the Room's next changes bring, and `reached(room, roomVersion, path)`
48
+ whether the held copy of that document was written later. A History revision names its
49
+ author, `{ kind: 'user', id }` or `{ kind: 'inbox', id, name }`; History of a Path no
50
+ document holds answers the removed document's revisions, newest first, with `deleted:
51
+ true`, which a link to the Path opens. Every member is asynchronous and every result a
52
+ detached snapshot; nothing returns the authorization, performs a request the App's code
53
+ composes, or exposes the browser store. A Room `rooms` names `locked` shows only online.
54
+
55
+ Next: [Refusals, deployment facts and the member](apps/runtime-refusals)
@@ -0,0 +1,19 @@
1
+ # Refusals, deployment facts and the member
2
+
3
+ How the MD Runtime API refuses and fails, and how App code reads the deployment facts and who uses it.
4
+
5
+ Every refusal and failure carries `code` and `retryable`: each Call and History answer
6
+ other than its result, a refused Save or Room Draft write, a returned Room Draft's reason,
7
+ a Room's refusal, the Connection Refusal and every error a member rejects with, beside its
8
+ message, a Provider refusal with the Provider's own `retryable`. Every code and value is
9
+ open: handle one you do not know by its `code` and `retryable`. Only a tag telling which
10
+ fields a value carries, such as `kind`, is closed: keep a branch for one you do not know.
11
+ A model with no usable types answers `types: null`.
12
+
13
+ Read the deployment facts with `observe('deployment-facts')`, an opaque value the host's
14
+ contract interprets. `observe('member')` answers who uses the App, the only way App code
15
+ learns it: the User the Provider signed in, `{ kind: 'user', id, name }` like a change's
16
+ `author`, so a Document whose `change.author.id` is its `id` is that User's own; `null`
17
+ until the Provider first names one, and where it names none. It is kept
18
+ with the Local Replicas, answers offline once known, and every port hears the next member
19
+ named; signing out answers `null`, then ends the observation with the authorization.
@@ -0,0 +1,14 @@
1
+ # The App runtime
2
+
3
+ The rules of the runtime's client an App's code reaches, one page per part.
4
+
5
+ These instructions address an agent in an environment with Git: obtain the App Repository,
6
+ change it, build, and push. They are documentation, not enforcement.
7
+
8
+ - [The MD Runtime API](apps/runtime-api)
9
+ - [Local Query rules](apps/local-query)
10
+ - [Local Search rules](apps/local-search)
11
+ - [Room Draft, Save, and outcome rules](apps/room-drafts)
12
+ - [Content safety and launch promises](apps/content-safety)
13
+ - [App code takes the client its host hands it and never constructs a Runtime](apps/client)
14
+ - [The Chat](apps/chat)
@@ -0,0 +1,12 @@
1
+ # Start an App
2
+
3
+ How to get an App's repository, build it and publish every change.
4
+
5
+ - An App with an `a_` reference already exists, even with no release yet, as every App your User makes in the panel does. Clone its `.git` address, `<origin>/app/<app_ref>.git` or its `source_url` in `list_apps`, with `git clone -c user.name=<agent-git-name> -c user.email=<agent-git-email> <address>`, so Git commits as you in every later step too. Run `npm ci --ignore-scripts`, then publish with `npm run publish`, never with `--name`.
6
+ - Git signs in as you with a credential your User makes for you on `<origin>/connections`, given as its password.
7
+ - When the Kit runs you, add `-c 'credential.helper=!kit git-credential'` to the clone instead, so the Kit signs Git in.
8
+ - Only when no App exists yet, clone `<origin>/app/new.git` the same way: it gives mdui, a minimal App in plain TypeScript with its test and `npm run publish`. Run `npm ci --ignore-scripts`, then `npm run publish -- --name "<display name>"`, which creates the App and prints its address and its `.git` address. Then `git remote set-url origin <that .git address>`; every later `npm run publish` goes there, without `--name`.
9
+ - Use any framework and build tool. `npm run build` leaves the whole release in `dist/`: the entry HTML, every file it loads, `app.json` and `schema.yaml`. The entry names files by relative paths (Vite: `base: './'`), carries no inline script and loads nothing from outside the release, so bundle fonts and libraries. A release holds at most <release-files> files and <release-size>.
10
+ - Your User sees a change only once it is published, so an ask to change an App is an ask to publish it: end every change with a commit and `npm run publish`, which builds, pushes `main` and the build, and prints `published` or the reason House refused. A `git push` of `main` alone publishes nothing and says so. A refused push changes nothing and the previous release keeps running.
11
+ - Without Git, zip the project folder after the build, without `node_modules` and `.env`, `upload` the ZIP to a Room and publish it with `publish_app_zip`.
12
+ - A page whose first draw is not yet the place it opened on, as one that draws its Room's documents once `observe` answers, registers `bridge.cooperate({ placed })` in its entry script before its first draw, where `placed` resolves once that place shows what it holds, as [the example](apps/example-tasks) does: House keeps its preparation surface over the page until then, and shows a page that registers none at its first draw. An open page keeps the release it loaded and runs the next one at its next load, so it needs no update code; `node_modules/@agentshouse/app-bridge/docs/families.md` describes each bridge member.
@@ -0,0 +1,16 @@
1
+ # Verify an App
2
+
3
+ What to check before an App is published and after.
4
+
5
+ Before `npm run publish`:
6
+
7
+ - `npm test` passes against the newest `@agentshouse/app-bridge` and `@agentshouse/mdruntime` (`npm install --ignore-scripts <name>@latest`), since every page gets House's newest runtime. Keep mdui's test: it runs the built page on `createMemoryAdapter` from `@agentshouse/mdruntime/memory` and `createHouseBridgeTestHost` from `@agentshouse/app-bridge/test-host`, with no House.
8
+ - Every slot type is in `schema.yaml` exactly as in the bound Room's `settings/schema.yaml`.
9
+ - The page works 360 pixels wide, offline, and reloaded at a deep address.
10
+
11
+ After it:
12
+
13
+ - `list_apps` names the App's `published_release`, whose `revision` is the `main` commit it was built from; a clone, a fetch and `git ls-remote` see `main` alone.
14
+ - Bind the Room once with `set_app_bindings`.
15
+ - See it yourself: sign your own browser in with `create_sign_in_code`, then open the App's url.
16
+ - Give your User its address. An open page keeps the release it loaded and takes the next one at its next load, offline too; nothing asks them to update.
@@ -0,0 +1,11 @@
1
+ # Get started
2
+
3
+ What House is, where your User signs up and how this client connects.
4
+
5
+ House keeps Markdown files in Rooms, which your User shares with other people and their agents.
6
+
7
+ Sign-up page: <origin>/sign-up
8
+
9
+ MCP address: <origin>
10
+
11
+ Your User signs up on that page; then add the MCP address to this client as a remote MCP server, and your User signs in when it asks.
package/guide/index.md ADDED
@@ -0,0 +1,12 @@
1
+ # House
2
+
3
+ Where House's guides and formats start: `open_guide` opens a page by its `path` or finds pages by `words`.
4
+
5
+ House keeps Markdown files in Rooms, which your User shares with other people and their agents.
6
+
7
+ While your User's My Room, which `list_rooms` marks, holds no `wayfinding-map`, open [House Onboarding](skills/house-onboarding) first.
8
+
9
+ - `apps/`, building an App over your User's Rooms: [Build an App](apps/build), and the functions House runs for it when a Trigger fires: [App functions](apps/functions).
10
+ - `reference/`, the formats House reads: [Access level](reference/access-level), [App manifest](reference/app-manifest), [Schema](reference/schema) and [Triggers](reference/triggers).
11
+ - `routines/`, the Routine the panel writes for My Room for each Agent it makes, naming that Agent, written as [Routine](reference/routine) says: [Work on ticket](routines/work-on-ticket).
12
+ - `skills/`, House's Skills: [Prototype an App](skills/prototype-app).
@@ -0,0 +1,40 @@
1
+ # Owner rules
2
+
3
+ What a Room is for and where work goes, the skills' output included.
4
+
5
+ A Room is where information people share is kept; it is not the place for
6
+ private information. Work goes into the Room it belongs to, or My Room, which
7
+ `list_rooms` marks, when none is named.
8
+
9
+ Every House answer carries the `url` of what it names; send the User that link.
10
+
11
+ The skills are already set up; never run `setup-matt-pocock-skills`.
12
+
13
+ ## Where skill output goes
14
+
15
+ - Glossary (`GLOSSARY.md`): `glossary.md`
16
+ - Decisions (ADRs): `decisions/NNNN-<slug>.md`
17
+ - Plan (spec): `projects/<name>/plan.md`
18
+ - Tasks (tickets): `projects/<name>/tasks/NN-<slug>.md`, with a
19
+ `Status:` line (`needs-triage`, `needs-info`, `ready-for-agent`,
20
+ `ready-for-human`, `wontfix`, or `done` once implemented), a
21
+ `Category:` line (`bug`, `enhancement`), a `Blocked by:` line and comments
22
+ under `## Comments`; triage takes no pull requests
23
+ - Rejected requests (triage): `out-of-scope/<concept>.md`
24
+ - Implementation notes (implement-spec): `projects/<name>/notes/`
25
+ - PR bodies (pr): `projects/<name>/prs/<branch>.md`
26
+ - Wayfinding map: one `wayfinding-map` document, `projects/<name>/map.md`,
27
+ and its tickets, `wayfinding-ticket` documents in order as
28
+ `projects/<name>/map/NN-<slug>.md`: a ticket carries its `title`, its
29
+ `map` (the map's path), its `kind` (its type) and `blocked_by` (its
30
+ blockers); a claim sets `status: in-progress` and the
31
+ `assignee`, and a resolution writes the Answer and sets `done`, or
32
+ `out-of-scope`
33
+ - Research: `research/<slug>.md`
34
+ - Architecture reports (improve-codebase-architecture): `architecture/<slug>.html`
35
+ - Handoffs: `handoffs/<slug>.md`
36
+ - Questionnaires: `questionnaires/<slug>.md`
37
+ - Retrospectives (retro): `retros/<date>-<slug>.md`
38
+ - Wizards: `wizards/<slug>.sh`; the values they capture stay out of the Room
39
+ - Learning: `learning/<topic>/`
40
+ - Prototype: one HTML file with every variant on one page.
@@ -0,0 +1,9 @@
1
+ # Access level
2
+
3
+ How much of a Room a grant or a Share lets its holder do with its text, and where.
4
+
5
+ Access level, `level` on a Room grant or a Share’s Room item, each level including the one before it: `search`, the Search level, reaches the Room through `search`, `shell` and `inspect` alone, each reply at most <mcp-read-size> of the Room’s text, with no copy anywhere; `open`, the Open level, also opens the Room in browser Apps while the browser is online, and acts as `search` everywhere else; `keep`, the Keep level, also copies the Room to the devices that keep it, offline included, and is the one `export` needs. Apps need `open` or `keep`.
6
+
7
+ ```json
8
+ { "room_ref": "r_ab12.1", "level": "open", "operations": ["write"] }
9
+ ```
@@ -0,0 +1,12 @@
1
+ # App manifest
2
+
3
+ What an App's `app.json` declares.
4
+
5
+ App manifest, `app.json` at an App’s root: `entry`, its HTML page, and `room_slots`, each with a `name`, `access` `read` or `write`, and `types` from the `schema.yaml` beside it, written like a Room schema; `set_app_bindings` fills a slot with Rooms. Where needed it adds `external_origins`, the https origins its page may reach; `conversations: true` to read your User’s conversations; `local_search: true` to call `search`; `inboxes: true` to show and answer customer chats, naming `inbox-chat` and `inbox-message` in `room_slots`; `house_acts`, the House acts it calls by their act names, such as `rooms/read` for your User’s Rooms or `rooms/rename`, never one only a person takes or one that changes what an App reaches, except that a Self-hosted Building's App may declare its administrators' acts, `building/people/read`, `building/people/add`, `building/people/remove`, `building/administrators/name`, `building/administrators/take`, `building/factor/require`, `building/factor/stop-requiring` and `building/factor/reset`, which its page calls in an administrator's browser once it has asked them to confirm each, `building/people/read` refusing anyone else `not_building_administrator`; `functions`, each a `name` and the `entry` file a Trigger runs on House's servers ([App functions](apps/functions)); and `theme_colour`, `#rrggbb`. A User who does not own the App is asked once to allow the House acts it declares, and again only for those a later release adds; a declined one is refused. [Build an App](apps/build) shows how its page works.
6
+
7
+ ```json
8
+ {
9
+ "entry": "index.html",
10
+ "room_slots": [{ "name": "tasks", "access": "write", "types": ["task"] }]
11
+ }
12
+ ```
@@ -0,0 +1,15 @@
1
+ # Routine
2
+
3
+ How a Routine document in the Private Room is written, one for each Room it serves.
4
+
5
+ Routine, `/rooms/private/rooms/<room-handle>/routines/<name>.md`, serving the Room `<room-handle>` names: `description`; `input`, a text saying what to send, empty if nothing; and `agent`, the identifier of the one of your User's current Agents it starts. The body is the instruction, which never leaves the Private Room. Writing it needs your User's write in that Room. House writes its card, the description, input and Agent, at `/rooms/<room-handle>/house/routines/<name>.md`, where every member reads it, and refuses a name a card there already holds as `routine_name_taken`. A Routine a second Room needs is a copy under that Room's handle. Anyone who writes that Room asks it with `send_routine_request` naming the card, and may instead name the `agent` with their own words; either starts at once. A Routine Request's input is text the Agent reads, and House checks no shape. Mail your conversation sends with `send_mail` and a request it sent reaches the conversation that request started, and that conversation's mail comes back to yours.
6
+
7
+ ```markdown
8
+ ---
9
+ description: Summarize a thread in five bullets.
10
+ input: The thread to summarize, as a ref or pasted text.
11
+ agent: 019a0000-0000-7000-8000-000000000001
12
+ ---
13
+
14
+ Read the thread and write five bullets under summaries/.
15
+ ```
@@ -0,0 +1,28 @@
1
+ # Schema
2
+
3
+ How a Room's `settings/schema.yaml` declares its document types.
4
+
5
+ Schema, `/rooms/<room>/settings/schema.yaml`: one JSON Schema in YAML. Each top-level key is an MD type holding the schema of its frontmatter; `$defs` holds shapes reused through `$ref: '#/$defs/<name>'`. An object setting neither `additionalProperties` nor `unevaluatedProperties` refuses other keys. House adds `reference` on a string at any depth, naming the types, or `attachment`, its value links to, and `cross_room: true` beside it, letting that be another Room's document of those types; a link or reference written as its `/rooms/<room>/` path is stored relative to the document; `sections`, a type's `##` headings, each `{ kind: text }` or `{ kind: list, items }`; and `member_document: true` on one type, whose documents name their member with `member`, a User Identifier from `list_members`. On a type, `create_roles` lists the Schema Roles that may create its documents and `delete_roles` those that may delete them, and changing a document's `type` needs both; on a field of a type's own `properties`, `change_roles` lists those that may change it, `initial_roles` those that may set it on a new document, and `transitions` the `{from, to, roles}` changes it may make, `null` standing for absent; `owner` and `member` are built in, `[]` allows nobody, and only someone who manages the Room's access changes them. `edit` creates or replaces the whole text, and may rewrite the documents a change breaks in the same call. A Room may use a Shared schema instead, which `use_shared_schema` chooses: its `settings/schema.yaml` is then a read-only copy of it.
6
+
7
+ ```yaml
8
+ person:
9
+ member_document: true
10
+ properties:
11
+ role: { type: string }
12
+ task:
13
+ properties:
14
+ title: { type: string }
15
+ status: { enum: [open, done] }
16
+ owner: { type: string, reference: person }
17
+ required: [title]
18
+ sections:
19
+ Notes: { kind: text }
20
+ ```
21
+
22
+ ```markdown
23
+ ---
24
+ type: person
25
+ member: <User Identifier from list_members>
26
+ role: Designer
27
+ ---
28
+ ```
@@ -0,0 +1,17 @@
1
+ # Triggers
2
+
3
+ How a Trigger's `condition` and `actions` are written for `create_trigger` and `edit_trigger`.
4
+
5
+ A Room's Triggers are its read-only `house-trigger` documents at `house/triggers/<trigger>.md`, which House writes.
6
+
7
+ `condition`: When it fires, e.g. `{on: "documents", scope: {type: "task"}, mode: "starts_matching", new_documents: false, match: {all: [{path: "/fields/status", eq: "review"}, {path: "/members/assignee", eq: "<User id>"}]}}`; for a new document in a folder, `{on: "documents", scope: {folder: "/answers"}, mode: "starts_matching", new_documents: true, match: {all: []}}`; for any edit of one document, `{on: "documents", scope: {document: "/notes/plan.md"}, mode: "field_changes", field: "/text"}`; `moved_between_rooms: true` fires only on a document moved in from or out to another Room, `false` on any other change; for items, `{on: "items", address: "<push address>", match: {path: "/json/ref", eq: "refs/heads/main"}}`. A clock is `{on: "clock", cron: "0 9 * * 1", time_zone: "Europe/Berlin"}`, or a day before each task is due: `{on: "clock", scope: {type: "task"}, date: "/fields/due", days: -1, at: "09:00", time_zone: "Europe/Berlin", match: <test>}`. In your Private Room alone, a notification to you: `{on: "notifications", match: {path: "/fields/kind", eq: "share-offer"}}`, testing its `house-notification` document's `/fields/kind` and its value fields, `match` optional; such a Trigger holds no `notify` action. A `/fields/…` or `/members/…` path reads only what the document's own type declares: a document with no `type` has no fields, whatever its front matter holds, so give it a `type` naming one in `settings/schema.yaml` that declares the field.
8
+
9
+ A message into a conversation a [Routine Request](reference/routine) of the Room started: `{on: "messages", match: {path: "/sender", eq: "requester"}}`, testing `/sender`, `/routine` and `/path`, the request's document, never its words.
10
+
11
+ `actions`: What it does; a `notify` action names whom it reaches, e.g. `{kind: "notify", title: "Ready to test", text: "A task waits.", to: {users: ["<User id>"], fields: ["/members/assignee"], roles: ["owner"]}}`, Users by id, the member a field of the matched document names, and every holder of a Schema Role; a `function` action names an App and one function its latest release declares, e.g. `{kind: "function", app: "a_…", function: "assign lead"}`, which you may add only for an App you hold that has this Room in a write slot of your bindings; [App functions](apps/functions) says how House runs it. `list_trigger_events` shows each run `ran` with its `release`, or `failed` with `function_failed` and its `error`, never run again, or `function_not_started` while House tries to start it, `final` after its last try.
12
+
13
+ In your Private Room alone, a `function` action naming no `app` runs one of your Environment functions ([wizard](skills/wizard)), e.g. `{kind: "function", function: "nightly backup"}`; elsewhere, or for a name you do not hold, it is refused `environment_function_not_found`. Kit runs its script with no terminal, the Event as JSON in the file `HOUSE_INPUT` names, one Event after another. `list_trigger_events` shows each run `ran`, or `failed` with `function_failed` and its `error`, never run again, with its `run`, `exit_code` and `output`; a Kit not connected at its turn reads `no_target` with `environment_offline`, never run later.
14
+
15
+ A Trigger acts on at most <trigger-events-per-hour> Events in each UTC hour, counting the Events of every version of it but those kept skipped or failed; `list_trigger_events` shows each Event past that number `missed: "skipped"` with `code: "cap_reached"`, which starts nothing, and its creator is told once per version. A Trigger whose own actions make what it fires on stops there, so narrow its condition.
16
+
17
+ A `routine` action starts a [Routine](reference/routine) of the Trigger's Room by its card `house/routines/<name>.md`: `{kind: "routine", card: "<name>", payload: "<input>"}`. No such card is refused `routine_not_found`; a retired Routine's Events show `routine_retired`.
@@ -0,0 +1,15 @@
1
+ ---
2
+ description: Work the Wayfinding ticket this request names, from its Question to its Answer.
3
+ input: The ticket to work on.
4
+ ---
5
+
6
+ # Work on ticket
7
+
8
+ The Routine an Agent runs when a person sets a Wayfinding ticket in progress with that Agent as its assignee.
9
+
10
+ Work the one ticket this request names, then stop:
11
+
12
+ 1. Open the `wayfinding-ticket` the request names and set its `conversation` to this conversation.
13
+ 2. Work it by its `kind`: for `research`, find out and say where you found it; for `prototype`, build the smallest thing that answers its Question; for `grilling`, ask your User until its Question is settled; for `task`, do what it asks.
14
+ 3. Write what you found or made in its Answer section and set its `status` to `done`.
15
+ 4. Start no other ticket, not even one this ticket unblocks.
@@ -0,0 +1,18 @@
1
+ # Build a Site
2
+
3
+ How to build a Site, an App at a public address anyone opens without signing in.
4
+
5
+ Build it as [Build an App](apps/build) says, with what follows. Anything private is an App.
6
+
7
+ - A Site starts with `create_site`: `name` is its address name, and the answer's `source_url` is its App's `.git` address to clone the same way.
8
+ - A Site shows the Rooms it published, as `published` names them: creating it publishes its bound Rooms, a release keeps the published data, and later Room edits stay private until `publish_site_data`. A publication whose `state` is `preparing` replaces the shown one once its screenshot is taken; `list_sites` names each Site's newest publication and its `state`, and `publish_site_data` with nothing changed since answers that publication. `unpublish_site` stops serving a Site and keeps it; `republish_site` or `publish_site_data` serves it again.
9
+ - Bind a Site's Rooms with `set_site_bindings`.
10
+ - A Site is public: anyone opens it, nobody signs in, and every visitor reads its bound Rooms, which must be your User's own and never the Private Room.
11
+ - Everything it shows lives as documents in its Room; put its demo data there, never in code.
12
+ - A visitor's edits stay in their browser and never reach House: write them with `save` as an App does.
13
+ - To receive messages from visitors, name an Intake Room with `set_site_intake_room` and send each with `runtime.call('site/submission', { content })`, online only.
14
+ - `describe_site` sets the title and description search engines show.
15
+ - With `google_analytics_id` set by `describe_site`, House measures a visitor only after they accept. While `bridge.onStatus` reports `analytics.measures`, ask them on the Site unless `analytics.choice` holds their answer, report it with `bridge.analyticsConsent('accept')` or `bridge.analyticsConsent('decline')`, and keep a way on every page to decline later, which reloads the page unmeasured.
16
+ - See it yourself: open its url, which needs no sign-in.
17
+
18
+ House serves each route as HTML by the [Entry Data Contract](sites/entry-data-contract), and [The App runtime on a Site](sites/runtime) says what the runtime does differently there.
@@ -0,0 +1,25 @@
1
+ # Entry Data Contract
2
+
3
+ How a Site App's `entry_data` has House serve each route as HTML from Rooms.
4
+
5
+ Entry Data Contract, `entry_data` in a Site App’s `app.json`: House serves each route as HTML from your Rooms before the App starts, running none of your code. Each of `routes` has a `path` (`/`, `/posts/:slug`), optional `query` (functional `?name` parameters with defaults), `queries` (Local Query objects with `types` and a `pathPrefix` at each scope, no `rooms`; `{"$param": "slug"}` takes an argument, `"as": "integer"` converts it; `boundQuery` from `@agentshouse/mdruntime/entry` fills the same query in your page), `interaction` (the queries its first interaction needs), `title`, `description` and `body`. A body node is text, `{text: v}`, `{markdown: v}` of a document, `{tag, attrs, children}`, `{each: v, as, children}` or `{if: v, then, else}`; a value `v` is a literal, `{param}`, `{at, pointer}` into a query result or `each` item, `{join: [v]}`, `{count: v}` or `{stem: v}`. An `img`, a document's images among them, loads lazily in the box its `width` and `height` name, 16:9 without them. `styles` lists release CSS files. A route that fails starts the App as usual, and the Site document names why.
6
+
7
+ ```json
8
+ {
9
+ "routes": [
10
+ {
11
+ "path": "/posts/:slug",
12
+ "queries": {
13
+ "post": {
14
+ "types": ["post"],
15
+ "pathPrefix": "posts",
16
+ "where": { "/slug": { "$param": "slug" } },
17
+ "select": { "fields": ["/title"], "markdown": true }
18
+ }
19
+ },
20
+ "title": { "at": "post", "pointer": "/documents/0/fields/title" },
21
+ "body": [{ "markdown": { "at": "post", "pointer": "/documents/0" } }]
22
+ }
23
+ ]
24
+ }
25
+ ```
@@ -0,0 +1,19 @@
1
+ # The App runtime on a Site
2
+
3
+ What the App runtime does differently on a Site's page.
4
+
5
+ A History revision or a Document's `change` written by a Site gives its `author` as `{ kind: 'site', id, name }`. `observe('member')` answers `null` on a Site, and a Document's `change` is `null` there, since the Provider delivers no time.
6
+
7
+ On a Site, every Save stays in the visitor's browser: write grants and revisions do not refuse it,
8
+ and its Pending Change shows in every query and across reloads until the browser's storage is
9
+ cleared. It is never sent: `observe('queue', room)` shows it `local`, Sync Status never waits on
10
+ it, and once the Room no longer lets it apply it leaves the queue and returns no Room Draft.
11
+
12
+ A Site's page fills its [Entry Data Contract](sites/entry-data-contract)'s
13
+ `{"$param": name}` arguments with `boundQuery` from `@agentshouse/mdruntime/entry`, as
14
+ House did for its HTML. While the Site prepares, a query a route's `interaction` names
15
+ answers from the entry's result when the page observes that descriptor, and every other
16
+ stays pending. House replaces its HTML with the page once its document changed after those
17
+ answers, or readiness is `ready`, and then held still for two animation frames, unless the
18
+ visitor uses the HTML: draw the route at once, never behind a placeholder. Before
19
+ readiness is `ready`, `push` loads a new page.
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: build-app
3
+ description: Build an App properly from its prototype and publish it into the same App, once the User has decided on the prototype's design; the build ticket of a map `prototype-app` opened.
4
+ ---
5
+
6
+ # Build an App
7
+
8
+ Build the App a prototype made, once the User has decided on its design, and publish it into the same App.
9
+
10
+ ## Only after the User's decision
11
+
12
+ Read the map `prototype-app` opened for this App. Start only when its design-decision ticket is resolved with the User's decision. Until then do nothing else: tell the User their decision on the prototype's design is missing, give them the prototype's address, and stop. Without such a map there is no decision: say so and offer [`prototype-app`](skills/prototype-app).
13
+
14
+ ## Build
15
+
16
+ Claim the build ticket. Starting from the User's decision, run `grill-with-docs`, then `to-spec`, then `implement`. Keep what they write where the Owner rules, `/rooms/private/owner-rules.md`, say. Each Skill named here is also a Command of its name, or the Guide page it links, for a client that has not installed it.
17
+
18
+ ## Publish into the same App
19
+
20
+ Publish into the App the prototype made, never a new one, so its address and bindings stay:
21
+
22
+ - where you run Git, from a clone of its `.git` address, with `npm run publish` and never `--name`, as [Start an App](apps/start) says;
23
+ - otherwise zip the project folder after its build, `dist/` included and `.env` and `node_modules/` left out, `upload` the ZIP to the Room and publish it with `publish_app_zip`, naming the App by the reference in the map's Notes.
24
+
25
+ Resolve the build ticket with the App's address and give the User the address.
@@ -0,0 +1,29 @@
1
+ ---
2
+ name: house-onboarding
3
+ description: Find out what a new User wants from House and keep their plan as a Wayfinding map and tickets in My Room; run it while My Room holds no `wayfinding-map`.
4
+ ---
5
+
6
+ # House Onboarding
7
+
8
+ Onboard your User: find out what they want and keep the plan as a map and tickets in My Room.
9
+
10
+ Run `wayfinder` to chart the map; this page adds only what is House's. `wayfinder` is also a Command of its name for a client that has not installed it, and the Owner rules, `/rooms/private/owner-rules.md`, say how a map and its tickets are written.
11
+
12
+ ## Open
13
+
14
+ - When `list_rooms` lists a Room your User does not own and its access is not `public`, they were invited to it: first tell them which Room it is, who invited them and what they may do there. `list_members` names its owner, and `list_rooms` their access.
15
+ - Then ask what they want.
16
+
17
+ ## Keep the plan
18
+
19
+ - Keep the map as one `wayfinding-map` and its tickets as `wayfinding-ticket` documents in My Room, which `list_rooms` marks with `my_room: true`. Chart the map even when the way looks clear: My Room's map is how House knows onboarding ran.
20
+ - Keep decisions about the account, billing, runtime or credentials in the Private Room, `/rooms/private`.
21
+ - Make the App for your User's goal a ticket.
22
+
23
+ ## My App
24
+
25
+ My App, `<origin>/app/my`, is your User's own App, and House's default My App shows the map and its tickets.
26
+
27
+ - When you can build and test code, build My App as [Build an App](apps/build) says and publish it into the App `list_apps` names `My App`. Keep its slot `rooms`, which holds your User's Rooms, so its binding stays.
28
+ - Otherwise leave House's default.
29
+ - When you cannot hand House a file, give your User the App's ZIP to upload to My App in the panel.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: prototype-app
3
+ description: Make a new App by publishing a prototype first; it is built properly only once the User has decided on its design.
4
+ ---
5
+
6
+ # Prototype an App
7
+
8
+ The User sees a working prototype before anything is built properly. A map holds the way: the prototype, published as the App's first release; the User's decision on its design; then `build-app`, which builds the App and publishes it into the same App.
9
+
10
+ Keep everything where the Owner rules, `/rooms/private/owner-rules.md`, say. Each Skill named here is also a Command of its name, or the Guide page it links, for a client that has not installed it.
11
+
12
+ ## 1. Open the map
13
+
14
+ In the Room the User names, or My Room when they name none, which `list_rooms` marks, chart a map as `wayfinder` does, but skip its grilling: the way is set here.
15
+
16
+ - **Destination:** the App the User asked for, built and published.
17
+ - **Notes:** this map's tickets do the work they name; the App's address and `a_` reference once the prototype is published.
18
+ - **Tickets**, each blocked by the one before:
19
+ 1. Prototype, `kind: task`: build a prototype and publish it as the App's first release.
20
+ 2. Design decision, `kind: grilling`: the User's decision on the prototype's design.
21
+ 3. Build, `kind: task`: run [`build-app`](skills/build-app).
22
+
23
+ ## 2. Publish the prototype
24
+
25
+ Claim the first ticket. Build the prototype as [Build an App](apps/build) says: its pages, their look and their flow, just enough for the User to judge the design.
26
+
27
+ Publish it as a new App, which creates it:
28
+
29
+ - where you run Git, with `npm run publish -- --name "<display name>"`;
30
+ - otherwise zip the project folder after its build, `dist/` included and `.env` and `node_modules/` left out, `upload` the ZIP to the Room and publish it with `publish_app_zip`, naming the display name and no App.
31
+
32
+ Write the App's address and reference into the map's Notes, resolve the ticket with them, and give the User the address.
33
+
34
+ ## 3. Record the User's decision
35
+
36
+ Claim the second ticket and ask the User to open the prototype and decide on its design: keep it, or what to change. A change they ask for before deciding is a new prototype release in the same App: `npm run publish` without `--name`, or `publish_app_zip` naming the App. Resolve the ticket with their decision in their words; never decide for them.
37
+
38
+ ## 4. Build
39
+
40
+ The third ticket runs [`build-app`](skills/build-app), in this session or a later one.