Byoi project customization

Mental model

A Byoi project is a Git repository that remains useful without the app. Cards, decisions, knowledge, context, prototypes, extend sessions, and configuration live as versioned files.

Customizing Byoi means changing the project declarative contract, mostly in byoi.config.json. The app reads that file to render views, collections, tabs, and actions. External agents can read the same whole repo as context before proposing changes.

What can be customized

V1 supports custom board columns, card types, AI routing, custom collections, extra card tabs, and AI actions attached to collections or tabs.

Custom collections create new project data types in the repo, such as releases, customers, experiments, incidents, or milestones. Each item is still Markdown with frontmatter, so it remains readable in Git and editable by any tool.

• Collections with list or board view.
• Fields of type string, enum, date, boolean, number, and relation.
• Relations from collections to cards.
• Extra card tabs with text or checklist content.
• AI actions with a closed prompt_template and proposal output.

Editing paths

There are three safe paths. First, edit byoi.config.json directly in the repo and let Byoi load the configuration. Second, use the product UI, which writes the file through GitProvider. Third, use /extend: an AI conversation that returns only a JSON fragment, validated by the same schema before it appears as an applicable proposal.

An external agent can customize the project by editing the repository, as long as it follows the documented schema. An internal Byoi call can propose the same kind of fragment. In both cases, secrets never go to the repo and AI writes must never happen without human confirmation.

Public form as a feedback channel

The public form creates captured cards on the board without requiring an account from the sender. It can be used by Byoi itself or by other systems that want to turn feedback, bug reports, or ideas into Markdown in the project repo.

Links to /f/<token> may receive origin, email, and returnTo. origin and email are saved into the generated card byoi:public-fields block. returnTo appears as a back link on the public page and confirmation, opening in the same tab.

By default, the public page does not show the Byoi top menu so it works well outside the product. Use chrome=byoi only when you want to keep app navigation. In public form settings, the menu checkbox adds that parameter to the copied link.

In the Byoi app, the global feedback CTA is configured by NEXT_PUBLIC_BYOI_FEEDBACK_URL. The value should be the complete public form URL; the app appends origin, email, and returnTo if they are not already present.

/f/<token>?origin=byoi-account-menu&email=user@example.com&returnTo=/projects/<projectId>/board

Config contract

Customization lives in byoi.config.json. Missing or invalid sections fall back to that section default without breaking the rest of runtime. Extra fields are preserved when Byoi loads and saves configuration.

AI must not return the whole config file for /extend. It should return only the new fragment inside a byoi-proposal block; merge is deterministic and preserves what already existed.

```byoi-proposal
{
  "collections": {
    "releases": {
      "label": "Releases",
      "folder": "releases",
      "view": "board",
      "board_by": "status",
      "fields": [
        { "key": "status", "type": "enum", "options": ["planned", "building", "shipped"], "required": true },
        { "key": "cards", "type": "relation", "multiple": true }
      ],
      "linkable_from": ["card"]
    }
  }
}
```

Custom collections

A collection defines a folder, a view, and the fields each item should have. Every item lives in folder/id-slug.md. Unknown files are ignored without error, and new fields added after old items exist receive defaults.

Reserved names cannot be used as collection folders: cards, decisions, knowledge, context, agents, agents/sessions, prototypes, assets, and byoi.config.json.

type CollectionDefinition = {
  label: string;
  folder: string;
  view: 'list' | 'board';
  board_by?: string;
  fields: FieldDefinition[];
  linkable_from?: Array<'card' | 'decision' | 'knowledge'>;
  actions?: AIActionDefinition[];
};

Tabs and AI actions

card_extensions.tabs adds card tabs without creating new files. Content lives in frontmatter.tabs.<slug> inside the card itself.

AI actions are declarative. prompt_template accepts only placeholders declared in inputs. The response comes back as a proposal, not as an automatic write. Checklist output uses deterministic text parsing, without a second AI call to structure the response.

{
  "card_extensions": {
    "tabs": [
      {
        "tab_label": "tests",
        "content_shape": "checklist",
        "ai_action": {
          "label": "Suggest tests",
          "inputs": [{ "type": "field", "key": "content" }],
          "prompt_template": "Create a test checklist for: {{field:content}}",
          "output": { "target": "checklist", "mode": "append" }
        }
      }
    ]
  }
}

How agents should use it

Coding agents can use the whole repo as project context: AGENTS.md, context, decisions, cards, knowledge, prototypes, collections-guide.md, and byoi.config.json. That lets them understand both the product and the customized workflow.

When customizing, the agent should read agents/collections-guide.md, propose only JSON inside the closed vocabulary, and record changes by commit. If the request does not fit the schema, the correct answer is to refuse and suggest registering a Byoi feature idea.

Deliberate limits

Customization is not arbitrary code execution. Users and AI do not define React components, SQL, scripts, or free-form logic inside the project. The vocabulary is small on purpose to preserve security, portability, and simplicity.

There is no parallel timeline either. Customization history is Git commits. When /extend applies a proposal, Byoi writes byoi.config.json and an agents/sessions file in the same commit.