Skip to content

Best practices (sample): a sample project in every workspace - #1200

Open
JorimTheuns wants to merge 7 commits into
mainfrom
best-practices-sample
Open

Best practices (sample): a sample project in every workspace#1200
JorimTheuns wants to merge 7 commits into
mainfrom
best-practices-sample

Conversation

@JorimTheuns

@JorimTheuns JorimTheuns commented Oct 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Requested by Jor · project thread

Before: a new workspace opens empty, so a new user has nothing to ask the assistant about and no example of how other organisations use dembrane.

After: every workspace has a "Best practices (sample)" project with 49 invented conversations of practitioners describing how they used dembrane (setup, the room, analysis, sharing back, and what went wrong), plus a seeded chat that answers "How do other organisations use dembrane, and how should I set up my first project?". A banner says the project is a sample and everything in it is invented. The onboarding video opens on this chat.

The copy doesn't count toward the workspace's usage or free-tier limits. On a free workspace it has its own small allowance instead: 10 chat questions across its chats (the seeded one included) and 1 report.

How

  • packages/samples: seedBestPractices(db, owner, workspaceId, now) and BEST_PRACTICES_IDS (uuid5 of the workspace). Idempotent; a deleted copy stays deleted; a newer fixture rewrites only the seeded conversations, chunks and the seeded chat's turns, never user chats, reports or project settings.
  • Migration 0015 adds project.is_sample and project.sample_version.
  • Org and workspace creation enqueue samples.seed-best-practices in their transaction; a periodic backfill seeds existing workspaces in batches (skips deleted workspaces, deleted copies, the demo and Millbrook orgs).
  • Exempted: audio-hour cap (stamp, usage, live lock), free chat count and 3-turn cap (BFF, reply, agentic; replaced by the sample's own 10-turn allowance), report gate and counts (replaced by 1 report on the sample), project counts, usage card, staff rollups, public stats, accounts analytics. The portal treats a sample as closed; conversations can't be moved in or out.
  • Frontend: disclosure banner; hides "Take part" and "Upload audio" on samples; the chat views don't block a sample chat at 3 turns and show the upgrade prompt when the server refuses.
  • Content: written from research into dembrane's own sales and founder recordings, CRM notes, PostHog usage, client project setups, the internal list of practitioners' recommendations, the "5 ways to use dembrane" article, the deliberative muscles draft (ideas only) and a facilitator's notes on repeated rounds, then reviewed against the docs and code for accuracy, anonymity and the brand guidelines. No real person, organisation, place or project.

Open questions

  1. The sample's free allowance (10 questions, 1 report) is a first guess; asked in the thread.
  2. External-client workspaces get a copy too.
  3. A newer fixture doesn't update the project name or context.
  4. The banner and the move error have machine translations in all 7 locales, recorded in machine-translations.json for review.

Tests: platform bun test --parallel 1155 pass / 0 fail (162 skipped need parity DB or provider credentials); sample tests 39 pass; typecheck, biome and package checks clean; frontend tsc clean, vitest on project routes 94 pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT

Generated by Claude Code

Generated by Claude Code

claude added 4 commits October 10, 2026 16:07
@claude
feat(samples): seed a best-practices sample project in every workspace
fce1795 
Each workspace gets its own copy of "Best practices (sample)": three
placeholder conversations of practitioners describing how they used
dembrane, plus a seeded chat that answers "How do other organisations
use dembrane, and how should I set up my first project?".

- db: expand migration 0015 adds project.is_sample and
  project.sample_version.
- samples: seedBestPractices(db, owner, workspaceId, now). It derives
  every id with uuid5 from the workspace (BEST_PRACTICES_IDS) and takes
  a per-copy advisory lock. It never resurrects a deleted copy and
  makes no writes when the copy is current. A newer fixture rewrites
  only the conversations, chunks and seeded chat turns; user chats and
  reports are left alone.
- samples: backfillBestPractices, an idempotent keyset backfill with a
  time budget that skips deleted workspaces and orgs, excluded demo
  orgs and copies a user deleted. The worker runs it every 10 minutes.
- tenancy and account: workspace creation enqueues
  samples.seed-best-practices inside the creation transaction
  (signup's personal workspace enqueues it best effort). Workspace
  removal soft-deletes the copy.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT
@claude
feat(limits): exempt sample projects from usage, limits and rollups
1add84a 
A sample project is not the workspace's own work, so it counts toward
no allowance or statistic:

- audio cap: stampOverCap, workspaceSeconds and both
  workspaceOverCapActive queries
- chat: the free chat allowance and the 3-turn cap on the BFF, reply
  and agentic paths
- reports: the free report check and countWorkspaceReports
- workspace and org project counts, the usage card, staff liveProjects,
  stats countedProjectIds and the accounts synthetic filter
- the portal: storage.project() reports conversations as closed, and
  conversations cannot move into or out of a sample
  (conversation.move_sample)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT
@claude
feat(frontend): show a disclosure banner on sample projects
04c2903 
The project home shows "This is a sample project. The organisations,
people and conversations in it are invented." on projects with
is_sample set. It also hides the Take part card and the Upload audio
shortcut there. Adds the friendly message for conversation.move_sample
and extracts and compiles the catalogs. Non-English locales are not
translated yet.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT
@claude
feat(samples): the best-practices conversations, context and seeded chat
2d5bffd 
42 invented conversations of practitioners describing how they used
dembrane, written from research into real use and reviewed against the
docs and code, replace the placeholder fixture. The seeded chat answers
the onboarding question from them, and the fixture test now checks the
brand rules users will read.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT
@github-actions

github-actions Bot commented Oct 10, 2026

Copy link
Copy Markdown
Contributor

Hi @claude!

Thank you for contributing to Dembrane ECHO! Before we consider your Pull Request, we ask that you sign our Contributor License Agreement (CLA). This is only required for your first Pull Request.

Please review the CLA, and sign it by adding your GitHub username to the contributors.yml file. Thanks!

@JorimTheuns JorimTheuns self-assigned this Oct 10, 2026
claude added 2 commits October 10, 2026 16:26
@claude
feat(limits): give the sample its own free-tier allowance
2bc0771 
On a free workspace the sample's chats share 10 user turns (the seeded
question included) and the sample gets one report of its own, so new
users can explore it without spending their free chat or report, and
model use on it stays bounded. The chat views stop blocking a sample
chat at three turns and show the limit when the server refuses.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT
@claude
fix(frontend): translate the sample banner and move error, refresh ca…
b806489 
…talogs

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT
@JorimTheuns JorimTheuns mentioned this pull request Oct 10, 2026
Draft
@claude
feat(samples): seven more best-practices conversations from new sources
9fc5c10 
Adds conversations on a whole participatory budget cycle, groups keeping
their own clustering, screens between repeated rounds, asking who was
missing, switching on only what a project needs, quiet voices in a
teacher college and residents taking over hosting. Sharpens four
existing ones, and corrects nine that said hosts can upload text: the
dashboard upload takes audio only, so text goes in through the portal's
text option.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016MNLytqu8PVd9qtSMkP7dT
@JorimTheuns
JorimTheuns marked this pull request as ready for review October 10, 2026 18:41

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@spashii spashii spashii approved these changes

Assignees

@JorimTheuns JorimTheuns

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@JorimTheuns @spashii @claude