# Black Ice — Complete Documentation > The invisible semantic layer powering AI-native global content. --- # Welcome to Black Ice > Learn what Black Ice is and how it helps manage product terminology.
Welcome to Black Ice # Launch faster. Own your brand in every market. Black Ice gives teams a single, governed source of truth for product naming, messaging, and market rules — so every campaign, landing page, and product launch goes out with the right words, in the right market, without last-minute firefighting.

The problem it solves

## Brand inconsistency is a product problem in disguise. When your product has different names in different markets — because legal said so, because the plan includes different features, because the term means something different in German — that complexity lives in spreadsheets, email threads, and tribal knowledge. Until it breaks. > *"The French team launched the campaign with the wrong plan name. The feature isn't available there. Legal flagged it after go-live."* > > — A story every global marketing team knows. Black Ice makes that complexity visible, governed, and connected to the teams who produce content — before it ships. ---

What it looks like in practice

## Your product — one source of truth, three markets | Market | Plan Name | Key Rules | |--------|-----------|-----------| | 🇺🇸 **US** | Pro | Includes Analytics, API Access, Collaboration, Custom Exports. No restrictions. Standard brand voice. | | 🇩🇪 **Germany** | Pro | Custom Exports available on Enterprise only. Formal register required. API retained as anglicism. Legal disclaimer required on pricing pages. | | 🇧🇷 **Brazil** | Pro | Analytics renamed *Análise de Dados* per brand approval. API Access not yet launched. Warm, conversational register. | > Every content producer — copywriter, campaign manager, localization vendor — works from the same approved data. No version confusion, no market mix-ups. ---

What your team gets

## Four pillars of brand governance

One approved source

Product names, feature terms, and market rules live in one place. Not three spreadsheets and a Notion doc.

Market-ready by default

Know exactly what's available where, what it's called, and what the brand voice requires — before the brief goes out.

Legal and brand approval baked in

Send terms for review via shareable link. Reviewers approve or comment without needing an account.

AI that uses your actual brand rules

When you use AI to draft or localize content, it reads your approved terminology and market conventions — not a generic prompt.

---

How it fits your workflow

## From setup to structured output
  1. Set up your product model — define plans, features, and platform terms once
  2. Add market rules — what's available where, what it's called, what register to use
  3. Get sign-off — legal, brand, and regional reviewers approve inline, no account required
  4. Share with your team — copywriters, agencies, and localization vendors all pull from the same approved source
  5. Connect to your AI tools — Black Ice exports your brand knowledge as structured context your AI tools actually use
---

Who uses Black Ice

## Built for cross-functional brand teams

Global marketing teams

Brief agencies and content teams with market-specific naming and messaging rules already approved.

Brand and legal teams

Review and approve product terminology before it reaches campaigns. Full audit trail of who approved what.

Content and localization managers

One governed source replaces fragmented glossaries, style guides, and market-specific instructions.

Product marketers

Define canonical product positioning per market. Engineering, sales, and support stay aligned without chasing you.

--- # Plans and pricing > Compare Free, Pro, and Builder plans for Black Ice. Black Ice offers three tiers designed to scale with your terminology management needs. ## Plan comparison | | **Free** | **Pro** | **Builder** | |---|---|---|---| | **Price** | €0/month | €49/month | €199/month | | **Concepts** | Up to 50 | Up to 350 | Unlimited | | **Markets** | Up to 3 | Up to 20 | Unlimited | | **Workspaces** | 1 | 1 | Up to 3 | | **Team members** | — | — | Up to 10 | | **Workspace API** | — | ✓ | ✓ | | **GitHub Sync** | — | — | ✓ | | **Email digests** | — | ✓ | ✓ | | **Priority support** | — | ✓ | ✓ | ## Free Ideal for individual language professionals exploring structured terminology. Includes the full ontology editor, knowledge graph, approval workflows, custom fields, and all export formats (JSON, Markdown, ZIP, PDF, CSV). ## Pro — €49/month For localization managers handling multiple markets. Adds higher concept and market limits, the Workspace API for external tool integration, email digests, alert preferences, and the unified Permissions panel for governing approval workflows. ## Builder — €199/month For teams and organizations. Adds team management with role-based access (owner, admin, editor, viewer), GitHub Sync for CI/CD distribution, multiple workspaces (up to 3), and unlimited concepts and markets. Includes a monthly 1-hour consultancy session with our team to set up and refine your agentic workflows — design, review, and tune your AI agent pipelines together. For deeper, ongoing engagements, see the Custom Partner plan. ## Annual billing Save approximately 17% with annual billing on Pro and Builder. Switch billing cadence anytime from **Settings → Subscription**. ## Upgrading and downgrading Upgrades take effect immediately and are prorated. Downgrades take effect at the end of the current billing period. If you exceed a lower tier's limits after downgrading, your data is preserved but you cannot add new entries until you're back under the limit. ## FAQ **Can I change plans later?** Yes — upgrade or downgrade at any time from Settings → Subscription. **What happens if I exceed my concept limit?** You won't lose data, but you'll need to upgrade to add new concepts. **Is there an enterprise plan?** [Contact us](/contact) to discuss custom pricing, SSO, and dedicated infrastructure for large organizations. **How do I cancel?** Open the Stripe customer portal from Settings → Subscription and cancel there. Access continues until the end of your billing period. --- # Best practices > Tips for structuring your ontology and managing terminology effectively. Follow these guidelines to get the most out of Black Ice and keep your ontology clean, scalable, and useful. ## Structure your classes thoughtfully Classes are the backbone of your ontology. Define them early and keep them stable. - **Use domain-specific names** — "Feature", "Plan", "Platform", "Campaign" are better than "Item" or "Thing" - **Keep classes mutually exclusive** — A concept should belong to exactly one class - **Add descriptions** — Future team members will thank you for documenting what each class represents - **Set translation policies** — Some classes (like "Plan") may use do-not-translate policies, while "Feature" terms need localization ## Name concepts clearly Concept names are the canonical, language-neutral identifiers for your terms. - **Use the English source term** as the concept name - **Be specific** — "MIDI Editor" is better than "Editor" - **Avoid abbreviations** unless they're the official product name - **Use title case** consistently ## Manage variants intentionally Allowed and forbidden variants are powerful governance tools. - **Allowed variants** — List acceptable alternatives (e.g., "Creator Starter Plan" alongside "Creator Starter") - **Forbidden variants** — Explicitly block incorrect usage (e.g., "Starter Pack", "Basic Plan") - **Review variants regularly** — As your product evolves, old variants may become incorrect ## Use market availability strategically Not every term is ready in every locale at the same time. - **Set availability early** — Mark source terms as "Available" and target terms as "Planned" during initial setup - **Track readiness per locale** — Use availability statuses to see at a glance which translations are live, pending, or blocked - **Review mismatches** — The concept detail page shows availability badges on each term, making it easy to spot gaps ## Keep relationships meaningful Semantic relationships make your ontology a connected graph, not a flat list. - **Define relationship types first** — Set up types like "hasFeature", "hasPillar", "isPartOf" before creating concept links - **Use bidirectional relationships** — They generate inverse labels automatically - **Don't over-connect** — Only create relationships that provide real navigational or structural value ## Approval workflow tips - **Write clear messages** for reviewers explaining what they're approving and why - **Set appropriate expiry dates** — Default is 30 days, but time-sensitive terms may need shorter windows - **Use role-based filtering** — Configure which approver roles can review specific term types --- # Quick start > A step-by-step guide to creating your first concept in Black Ice. Get up and running with Black Ice in under 5 minutes. This guide walks you through creating your first concept, connecting it to others, and adding translations. ## Prerequisites - A Black Ice account (sign up at the login page) - A workspace is automatically created when you sign up ## Step 1: Explore your workspace After signing in, you'll land on the **Dashboard**. This shows your ontology stats, recent activity, and quick actions. Your workspace already has a source locale (English US by default). ## Step 2: Create your first class Navigate to **Classes** in the sidebar. Classes are categories that group your concepts — like "Feature", "Plan", or "Platform". 1. Click **Add Class** 2. Enter a name (e.g., "Feature") and an optional description 3. Choose a color and translation policy 4. Click **Create** ## Step 3: Add a concept Go to **Concepts** and click **Create Concept**. 1. Select the class you just created 2. Enter a name (e.g., "MIDI Editor") 3. Add an optional description 4. Click **Create** — Black Ice auto-generates a unique concept ID ## Step 4: Add translations Open your new concept and scroll to the **Terms** section. 1. Your source term is pre-filled from the concept name 2. Click **Add Target Term** to add a translation 3. Select a locale (e.g., "Spanish (ES)") 4. Enter the preferred term and any allowed/forbidden variants 5. Set the approval status ## Step 5: Set market availability Each term — source and target — has a **Market Availability** dropdown. 1. In the source term card, set availability (e.g., "Available") 2. In each target term card, set its own availability independently 3. Use this to track which translations are live, planned, or blocked > Market availability is tracked per term, not per concept. This lets you manage rollout status for each locale separately. ## Step 6: Define relationship types and connect concepts Relationships are what turn a flat list of concepts into a connected, navigable ontology. They express how concepts relate to each other — e.g., a Plan *hasFeature* a Feature, or a Feature *isPartOf* a Plan. **First, create a relationship type:** 1. Navigate to **Relationships** in the sidebar 2. Click **Add Type** 3. Enter a label (e.g., "hasFeature"), a machine value, and an optional inverse label (e.g., "isFeatureOf") 4. Choose directionality — **unidirectional** or **bidirectional** (bidirectional auto-creates the inverse) **Then, connect two concepts:** 1. Open a concept's detail page 2. Scroll to the **Semantic Relationships** section 3. Click **Add Relationship** 4. Select the relationship type and the target concept 5. The relationship appears on both concepts if bidirectional > Relationships power the **Knowledge Graph** and structured exports. The more intentionally you connect concepts, the more useful your ontology becomes for downstream consumers — including AI tools. ## Step 7: Visualize your ontology Navigate to **Knowledge Graph** in the sidebar. You'll see your concepts as nodes, connected by the relationships you defined. Use the filters to focus on specific classes or relationship types. Toggle **One-Hop** to reveal second-level connections. ## What's next? - [Best practices →](/docs/getting-started/best-practices) — Tips for structuring your ontology - [Import & Export →](/docs/guides/csv-import) — Bulk import existing terminology - [Approval workflows →](/docs/guides/approval-workflow) — Send terms for review --- # Getting started with AI > Connect your Black Ice ontology to AI models in minutes. ## Why connect AI to your ontology? Black Ice structures your terminology, market rules, and brand voice. AI models consume that structure and turn it into governed content — translations, copy, QA checks — without guessing. > Without an ontology, AI writes fluently. With one, it writes *correctly*. ## The 3-step pattern Every AI integration follows the same basic flow: **1. Export your ontology** Go to **Settings → GitHub Sync** and push your workspace to a repository. This generates a structured Markdown bundle containing your concepts, terms, market definitions, and relationship maps — and keeps it automatically updated every time you sync. Alternatively, use **Export → JSON Schema** or **Export → CSV** for one-off workflows. **2. Connect your AI tool to the repo** The recommended approach is to **link your AI tool directly to the GitHub repo** so it always reads the latest ontology — no manual uploads, no stale context. | AI Tool | Recommended setup | |---|---| | Claude | **Connect your Claude Project to the GitHub repo** — always-current context, zero re-uploads | | Claude Code | Point it at the same repo — it reads and operates on files directly | | ChatGPT | Upload the export as a knowledge file in a **Custom GPT** (manual re-upload on changes) | | Gemini | Paste into the prompt — the 1M token window handles large ontologies | | Ollama | Load as a system prompt in your local pipeline (use `git pull` to stay current) | > **Why GitHub-linked?** When you connect Claude Projects to the same repo that GitHub Sync pushes to, every concept update, term approval, or market definition change in Black Ice is automatically available in your next Claude session. No re-uploading, no re-prompting, no stale context. **3. Prompt with semantic context** Your prompts no longer need to explain terminology, tone, or market rules. The ontology already contains all of that. Instead, your prompts become task-focused: - *"Write a landing page for the Spain market"* - *"Review these translated strings for terminology consistency"* - *"Localize only the concepts that changed since last sprint"* ## What can you do with it? - **Generate market-specific content** without briefing docs - **QA translations** against your approved terminology - **Run delta localization** — only translate what changed - **Enforce consistency** across multiple projects from a single ontology - **Run fully local pipelines** for regulated industries ## Recommended integration: Claude + GitHub Sync Claude's instruction-following precision and Claude Projects' GitHub integration make it the strongest fit for ontology-driven workflows. Enable GitHub Sync in Black Ice, connect your Claude Project to the same repo, and every session starts with your latest ontology — no uploads required. Claude Code extends this into agentic pipelines that operate directly on your repository. → See the full guide: [Black Ice + AI: What Your Ontology Unlocks](/docs/integrations/ai-integrations-overview) ## Next steps - [Set up GitHub Sync](/docs/integrations/github-sync) to export your ontology - [Read the full AI integrations guide](/docs/integrations/ai-integrations-overview) for model-specific workflows - [Define your market rules](/docs/features/market-definitions) so AI models know your brand voice per locale --- # FAQ > Answers to common questions about Black Ice. Answers to the most common questions about Black Ice. ## General **What is Black Ice?** Black Ice is a semantic governance platform that helps teams govern how product terminology is defined, translated, and adapted across markets. It generates a structured bundle of markdown files — your ontology, translation rules, and market profiles — that AI localization pipelines consume directly. **Is Black Ice a translation tool?** No. Black Ice manages the semantic layer — the governed terminology, market context, and Culture DNA — that your AI pipeline needs to generate accurate, brand-consistent target content. The pipeline localizes automatically from that foundation. **What happens to the translator?** The role evolves. Translators become market owners — they architect the meaning, validate the terminology, and define the Culture DNA for their markets. The AI pipeline handles content generation. The market owner governs the rules it runs on and QAs the output. **Do I need technical knowledge to use Black Ice?** No. Black Ice is designed for terminology managers, localization PMs, and product teams. The interface is visual and no coding is required. ## Data & Import **Can I import existing terminology?** Yes. Black Ice supports CSV and Excel import with column mapping, duplicate detection, and conflict resolution. **What export formats are available?** You can export your ontology as CSV, JSON, or a structured ontology format. Column selection is configurable for CSV exports. **Can I connect Black Ice to my TMS?** Builder plan users can sync their ontology to a GitHub repository, which can trigger CI/CD pipelines to push data to any TMS with API access. ## Languages & Markets **What languages are supported?** Black Ice supports any language. You define your own locales with language codes, native names, and text direction (LTR/RTL). **How many markets can I manage?** Free plan: up to 3 markets. Pro: up to 20. Builder: unlimited. **What is market availability?** Market availability is a per-term status that tracks whether a source or target term is live, planned, unapproved, or not available in its locale. Each term has its own availability setting, giving you granular control over rollout readiness. ## Collaboration **How do I invite team members?** Go to **Settings → Team Management** and send an invite by email. Team members can be assigned roles: Admin, Editor, or Viewer. **How do approvals work?** You select terms and send them for review via a shareable link. The reviewer (who doesn't need a Black Ice account) can approve or reject each term with comments. All decisions are recorded in the approval history. **Can multiple people edit the same workspace?** Yes. Team members with Editor or Admin roles can create and modify concepts, terms, and relationships simultaneously. ## Security & Privacy **Where is my data stored?** All data is stored in a secure cloud database with row-level security policies. Only authenticated users with the correct workspace permissions can access your data. **Can I delete my account and data?** Yes. Go to **Settings → Account** to delete your account. This permanently removes all your data. --- # Glossary > Definitions of key terms used in Black Ice. Key terms used throughout Black Ice and this documentation. ## Concept A language-neutral unit of meaning in your ontology. Each concept has a unique auto-generated ID, a name, a class, and one or more terms in different locales. Example: "MIDI Editor" is a concept of class "Feature". ## Class A category that groups related concepts. Classes define the type of thing a concept represents — such as Feature, Plan, Platform, or Campaign. Each concept belongs to exactly one class. ## Source term The canonical term for a concept in your workspace's source locale (typically English). The source term serves as the reference for all translations. ## Target term A translation of a concept in a specific locale. Each target term includes the preferred translation, optional allowed/forbidden variants, notes, and an approval status. ## Locale A language-region combination used for translations (e.g., `en-us`, `es-es`, `de-de`). Each locale has a name, native name, text direction, and optional Culture DNA configuration. ## Culture DNA A structured set of guidelines attached to a locale that defines voice, tone, terminology rules, UX microcopy standards, and cultural pragmatics for that market. Used to ensure translations align with local expectations. ## Market A geographic or business region where your product is available (e.g., US, EU, LATAM, APAC). Markets correspond to locales in your workspace. ## Market availability A per-term status indicating whether a source or target term is live, planned, unapproved, or not available in its locale. Each term tracks availability independently, enabling granular rollout control. ## Semantic relationship A typed connection between two concepts (e.g., "Creator Starter" *hasFeature* "MIDI Editor"). Relationships can be unidirectional or bidirectional and include inverse labels. ## Relationship type A reusable definition for a kind of semantic connection (e.g., `hasFeature` / `isFeatureOf`). Relationship types are defined per workspace and include labels, inverse labels, and directionality. ## Ontology The complete structured system of concepts, terms, relationships, classes, and market availability statuses in your workspace. Your ontology is what you export, sync, and share. ## Approval workflow The process of sending terms for review to stakeholders via shareable links. Reviewers can approve or reject individual terms with comments. All decisions are recorded with timestamps. ## Workspace An isolated environment containing your ontology, team members, and settings. Each workspace has an owner and can include Admins, Editors, and Viewers. ## Knowledge graph A visual representation of your ontology showing concepts as nodes and semantic relationships as edges. The graph is interactive and filterable by class and relationship type. --- # Support > How to get help with Black Ice. Need help with Black Ice? Here's how to reach us. ## Contact form For general questions, feature requests, or partnership inquiries, use our [contact form](/contact). We typically respond within 24 hours on business days. ## Community Join the **Black Ice Discord community** to connect with other terminology professionals, share best practices, and get help from the community. [Join Discord →](https://discord.gg/4CuCQvsh) ## Email support Pro and Builder plan subscribers receive priority email support. Reach out at the email listed in your account settings. ## Bug reports If you encounter a bug, please report it in the **#black-ice-feedback** channel on our [Discord server](https://discord.gg/4CuCQvsh). When reporting, please include: 1. **What you were trying to do** — the action you performed 2. **What happened** — the unexpected behavior 3. **What you expected** — the correct behavior 4. **Screenshots** — if applicable ## Feature requests We love hearing how Black Ice can better serve your workflow. Submit feature requests through the [contact form](/contact) or discuss them in the Discord community. ## Documentation You're already here! Browse the sidebar to explore guides, feature documentation, and Integrations (GitHub). Use **Ctrl+K** (or **⌘K** on Mac) to search across all articles. --- # Classes > How Black Ice structures your product terminology as a connected ontology. Classes are the foundation of your ontology. They define the *type* of thing each concept represents — giving structure, meaning, and governance rules to your terminology. ## What is a class? A class is a category that groups related concepts. Think of classes as the taxonomy layer of your ontology: - **Feature** — A specific capability or function in your product - **Plan** — A pricing tier or subscription level - **Platform** — A top-level product or ecosystem - **Campaign** — A marketing initiative or promotional concept Every concept belongs to exactly one class. ## Creating a class Navigate to **Classes** in the sidebar and click **Add Class**. | Field | Description | |-------|-------------| | **Name** | The class label (e.g., "Feature"). Used to generate concept ID prefixes. | | **Description** | What this class represents. Helps team members understand when to use it. | | **Color** | Visual identifier used throughout the UI and knowledge graph. | | **Translation policy** | Sets the default localization rule: Prefer Adapt or Do Not Translate. Can be overridden per market. | ## Translation policies Each class carries a translation policy that governs how its concepts should be handled during localization: | Policy | Meaning | |--------|---------| | **Prefer Adapt** | Localize if a good equivalent exists; English fallback acceptable | | **Do Not Translate** | Verbatim. No adaptation, no substitution | The policy is applied at creation — a contributor adding a term to a class marked "Do Not Translate" gets the constraint before they type anything, not after a linguist catches it in QA. ## Market overrides When reality is more nuanced, market-level overrides let you flip the policy for specific locales without changing the class default. For example, a product name class might be "Do Not Translate" globally — but Japan and China need adapted forms. Instead of creating a separate class, you add market overrides: ```text Class: "Plan" Default: Do Not Translate Override: ja-jp → Prefer Adapt Override: zh-cn → Prefer Adapt ``` To manage overrides, open the **Overrides** dialog from the Classes table. Each row shows whether a market inherits the class default or has an explicit override. You can set or clear overrides per locale. The design principle: **status describes intent, scope describes where.** Geography is never encoded in the policy name. ## Class-based concept IDs When you create a concept, Black Ice auto-generates a unique ID based on the class name. For example, a concept in the "Feature" class might get the ID `feat_00000001`. This ensures IDs are: - **Human-readable** — You can tell the class from the prefix - **Unique** — Sequential numbering prevents collisions - **Stable** — IDs never change, even if the concept name does ## Managing classes You can edit a class's name, description, color, and translation policy at any time. Deleting a class requires removing all concepts in that class first. > Classes are workspace-specific. Each workspace maintains its own set of classes independent of other workspaces. --- # Concepts & IDs > How concepts and auto-generated IDs work in Black Ice. Concepts are the central building blocks of your ontology. Each concept represents a single unit of meaning — a product feature, a pricing plan, a platform element — independent of any specific language. ## What is a concept? A concept is a language-neutral entity with: - A **unique ID** (auto-generated from the class prefix) - A **name** (the canonical English label) - A **class** (the type of thing it represents) - An optional **description** - One or more **terms** in different locales - **Market availability** tracking term readiness per locale - **Semantic relationships** linking it to other concepts ## Auto-generated concept IDs When you create a concept, Black Ice generates a unique ID based on the class: ``` feat_00000001 → First concept in the "Feature" class plan_00000002 → Second concept in the "Plan" class plat_00000001 → First concept in the "Platform" class ``` The prefix is derived from the first four characters of the class name. The number increments automatically and is padded to 8 digits. **IDs are permanent.** Once assigned, a concept ID never changes — even if you rename the concept or change its class. This makes IDs safe to use as stable references in external systems. ## Creating a concept Navigate to **Concepts** and click **Create Concept**: 1. Select a class 2. Enter a name 3. Add an optional description 4. Click **Create** The concept is created with a source term matching the name you entered. ## Concept detail view Opening a concept shows: - **Basic info** — Name, class, description, concept ID - **Source term** — The primary term in your source locale - **Target terms** — Translations in other locales - **Market availability** — Per-term readiness status across locales - **Semantic relationships** — Connections to other concepts - **Custom fields** — Any workspace-defined custom attributes ## Bulk operations You can import concepts in bulk via CSV or Excel. See [CSV & Excel import](/docs/features/csv-and-excel-import) for details. --- # Semantic relationships > How semantic relationships connect concepts in your ontology. Semantic relationships connect concepts to each other, transforming a flat list of terms into a structured, navigable ontology. ## What is a semantic relationship? A semantic relationship is a typed link between two concepts. For example: - "Creator Starter" **hasFeature** "MIDI Editor" - "MIDI Editor" **isFeatureOf** "Creator Starter" Relationships give your ontology structure and meaning — they express how concepts relate to each other in your product domain. Without relationships, concepts are isolated entries. With them, your data becomes a connected knowledge system that reflects real product architecture. ## Relationship types Before creating relationships between concepts, you define **relationship types** at the workspace level. Navigate to **Relationships** in the sidebar to manage them. Each relationship type has: | Field | Description | |-------|-------------| | **Label** | The forward label (e.g., "hasFeature") | | **Inverse label** | The reverse label shown from the target's perspective (e.g., "isFeatureOf") | | **Value** | A machine-readable key used in exports (e.g., "hasfeature") | | **Directionality** | Whether the relationship works in one or both directions | | **Description** | What this relationship type represents | ### Common relationship types | Label | Inverse | Use case | |-------|---------|----------| | `hasFeature` | `isFeatureOf` | A plan includes a feature | | `hasPillar` | `isPillarOf` | A platform has a core domain | | `hasPlan` | `isPartOfPlanGroup` | A plan group contains a pricing plan | | `isRelatedTo` | `isRelatedTo` | General association between concepts | | `requiresDisclaimer` | — | A concept requires a legal disclaimer | | `dependsOn` | `isDependencyOf` | A feature depends on another | ## Bidirectional vs. unidirectional This is one of the most important decisions when defining a relationship type. ### Bidirectional relationships When a relationship is **bidirectional**, creating a link from A → B **automatically creates the inverse** from B → A. You don't need to create both manually. For example, if you define a bidirectional type with label `hasFeature` and inverse label `isFeatureOf`: - You link "Creator Starter" → "MIDI Editor" using `hasFeature` - Black Ice automatically shows "MIDI Editor" → "Creator Starter" using `isFeatureOf` Both links are visible in the Concept Detail view and the Knowledge Graph. The inverse relationship appears with a **bidirectional badge** so you can distinguish auto-created links from manually created ones. ### Unidirectional relationships When a relationship is **unidirectional**, only the direction you explicitly create exists. Creating A → B does **not** create B → A. Use unidirectional relationships when the reverse direction isn't meaningful — for example, `requiresDisclaimer` makes sense from concept to disclaimer, but not the other way around. ## Inverse labels The **inverse label** defines how a relationship reads from the target concept's perspective. This is what makes your ontology readable from any entry point: | From concept A | Label | From concept B | Inverse label | |----------------|-------|----------------|---------------| | "Pro Plan" | `hasFeature` | "Analytics" | `isFeatureOf` | | "Platform" | `hasPillar` | "Music Creation" | `isPillarOf` | When you view "Analytics" in the concept detail, you'll see the inverse: `isFeatureOf → Pro Plan`. This lets every team member navigate the ontology naturally, regardless of which concept they start from. > **Tip:** For symmetric relationships like `isRelatedTo`, set the inverse label to the same value as the forward label. ## Creating relationships 1. Open a concept's detail view 2. Scroll to the **Semantic Relationships** section 3. Click **Add Relationship** 4. Select the relationship type from the dropdown 5. Search and select the target concept 6. Click **Create** — done For bidirectional types, the inverse link is created automatically. You'll see it immediately on the target concept's detail page. ## Deleting relationships Hover over any relationship row and click the delete icon. For bidirectional relationships, deleting the forward link also removes the auto-created inverse. ## Managing relationship types Navigate to **Relationships** in the sidebar to view, create, edit, or delete relationship types. > **Warning:** Deleting a relationship type removes **all relationships of that type** across your entire ontology. This action cannot be undone. ## How relationships power the Knowledge Graph Every relationship you create becomes an edge in the [Knowledge Graph](/docs/features/knowledge-graph). The graph uses your relationship types as edge labels and your concept classes as node colors, giving you an interactive, visual map of your entire product ontology. Relationships also appear in structured exports (JSON, CSV), making them available to downstream tools, AI prompts, and content systems. --- # Knowledge graph > Visualize your ontology with the interactive knowledge graph. The Knowledge Graph is an interactive visualization of your entire ontology — concepts as nodes, relationships as edges — giving you a bird's-eye view of how your product domain fits together. ## Accessing the graph Navigate to **Knowledge Graph** in the sidebar. The graph loads automatically with all concepts and relationships in your current workspace. ## Reading the graph - **Nodes** represent concepts, colored by their class - **Edges** represent semantic relationships, labeled with the relationship type - **Node size** reflects the number of connections — concepts with more relationships appear larger The graph uses an automatic **Dagre layout algorithm** that arranges nodes hierarchically, positioning related concepts near each other for readability. ## Interacting with the graph | Action | Result | |--------|--------| | **Click a node** | Opens the concept detail panel | | **Drag a node** | Repositions it in the graph | | **Scroll wheel** | Zoom in/out | | **Click and drag background** | Pan the view | ## One-Hop toggle The **One-Hop** toggle (found in the graph toolbar) controls how deep the visualization goes: - **Off** — Shows only direct (Level 1) connections from the selected concept - **On** — Expands to show Level 2 connections — concepts connected to your direct connections This is useful for exploring how concepts cluster. For example, selecting a Plan concept with One-Hop enabled shows not just its features, but also the features' own dependencies and related concepts. ## Filtering Use the filter panel to focus on specific parts of your ontology: - **By class** — Show only concepts of a specific class (e.g., only Features) - **By relationship type** — Show only specific relationship types (e.g., only `hasFeature` links) Filters are combinable — you can show only Feature concepts connected by `hasFeature` relationships, hiding everything else. ## Graph stats The stats panel shows: - Total concepts and relationships displayed - Breakdown by class - Most connected concepts ## Bidirectional relationships in the graph Bidirectional relationships appear as edges with arrows in both directions. The forward label is shown on the edge; hovering reveals the inverse label. This reflects the auto-inverse logic — when you create a bidirectional relationship, both directions appear in the graph automatically. ## Tips for a useful graph - **Define classes consistently** — classes determine node colors, so a clear class taxonomy makes the graph immediately readable - **Use descriptive relationship labels** — edge labels should be scannable at a glance (`hasFeature` is better than `rel1`) - **Start with filters** — large ontologies are easier to explore one class or relationship type at a time - **Use One-Hop for discovery** — enable it to find unexpected connections between distant parts of your ontology --- # Custom fields > Extend your ontology with custom metadata fields on concepts and terms. Custom fields let you attach additional metadata to concepts and terms beyond the built-in attributes — without changing the underlying data model. ## Why custom fields? Every team has domain-specific metadata that doesn't fit neatly into a generic ontology structure. Custom fields let you track things like: - **Internal product codes** or SKU references - **Launch dates** or deprecation dates - **Compliance flags** (e.g., "requires legal review") - **Priority scores** or lifecycle stages - **External URLs** to specifications, Figma files, or Jira tickets Instead of overloading the description field or maintaining a parallel spreadsheet, custom fields keep this data structured, searchable, and co-located with the concepts it belongs to. ## Field types Custom fields support six data types: | Type | Description | Example | |------|-------------|---------| | **Text** | Free-form string | `"PROD-4821"` | | **Number** | Numeric value | `42` | | **Date** | Calendar date | `2025-03-15` | | **Boolean** | True/false toggle | `true` | | **Select** | Dropdown with predefined options | `"In Review"` | | **URL** | Clickable link | `https://figma.com/file/...` | ## Applies to: concepts or terms Each custom field definition specifies whether it applies to **concepts** or **terms**: - **Concept-level fields** appear in the Concept Detail view, directly after the Class selector. Use these for metadata that applies to the concept as a whole (e.g., internal ID, launch date, compliance status). - **Term-level fields** appear inline within source and target term forms. Use these for metadata specific to a particular translation or locale (e.g., character count limit, reviewer name). ## Scoping by class You can optionally restrict a custom field to a specific **class**. For example: - A `"Launch Date"` field that only appears on concepts with class **Plan** - A `"Compliance Flag"` field that only appears on **Feature** concepts If no class is selected, the field appears on all concepts (or all terms, depending on the applies-to setting). ## Creating custom fields 1. Navigate to the **Concepts** dashboard 2. Open the **Actions** dropdown in the toolbar 3. Click **Custom Fields** 4. Click **Add Field** 5. Configure the field: - **Name** — a descriptive label (e.g., "Internal SKU") - **Type** — choose from Text, Number, Date, Boolean, Select, or URL - **Applies to** — Concept or Term - **Class restriction** — optionally limit to a specific class - **Required** — whether the field must be filled in - **Options** — for Select fields, define the dropdown choices 6. Click **Save** The field immediately appears on all matching concepts or terms. ## Editing and deleting fields From the Custom Fields manager: - **Edit** a field to change its name, type, or options. Existing values are preserved where compatible. - **Delete** a field to remove it and all its stored values permanently. > **Warning:** Deleting a custom field removes all saved values across every concept or term. This cannot be undone. ## Custom fields during concept creation Custom fields work during concept creation too. When you create a new concept, any applicable custom fields appear inline in the form. Values are buffered locally and saved automatically once the concept is created. ## Display order Fields appear in the order you define them. You can adjust the display order from the Custom Fields manager to control how fields are presented in the concept and term forms. ## Custom fields in exports Custom field values are included in structured exports (JSON, CSV), making them available to downstream tools, content systems, and AI workflows. Each field appears as a named column or property in the export output. --- # Source & target terms > How to manage multilingual terms, culture guidelines, and approval workflows. Every concept in Black Ice has one or more **terms** — the actual words used in specific languages and markets. Terms are the human-facing layer of your ontology. ## Source vs. target terms **Source term** — The canonical term in your workspace's source locale (typically English). This is the reference that all translations are based on. Each concept has exactly one source term. **Target term** — A translation of the concept in another locale. Each concept can have multiple target terms, one per locale. ## Term fields | Field | Description | |-------|-------------| | **Preferred term** | The approved translation (e.g., "Editor MIDI" in French) | | **Allowed variants** | Acceptable alternatives (e.g., "Éditeur MIDI") | | **Forbidden variants** | Explicitly blocked alternatives (e.g., "MIDI Éditeur") | | **Usage context (start)** | How the term appears at the start of a sentence (target terms only) | | **Usage context (mid)** | How the term appears mid-sentence (target terms only) | | **Notes** | Internal notes for translators or reviewers | | **Status** | Approval status: Pending, Approved, or Rejected | | **Market availability** | Whether this term is available, restricted, or unavailable in specific markets | ## Variants Variants provide governance beyond the preferred term: - **Allowed variants** are acceptable alternatives that won't trigger errors in quality checks - **Forbidden variants** are explicitly wrong — useful for catching common mistranslations or outdated terms ## Status workflow Terms follow a simple status workflow: 1. **Pending** — Newly created, awaiting review 2. **Approved** — Reviewed and accepted by a stakeholder 3. **Rejected** — Reviewed and declined, with comments explaining why Status can be changed manually or through the [approval workflow](/docs/features/approval-workflows). ## Adding terms Open any concept and scroll to the **Terms** section: 1. The source term is pre-filled from the concept name 2. Click **Add Target Term** to create a translation 3. Select the target locale 4. Fill in the preferred term and any variants 5. Save — the term is created with "Pending" status by default --- # Batch availability updates > Update availability across many concepts at once. Manually toggling availability one concept at a time is fine for small ontologies — but when you launch a new market or roll out a feature, you need bulk operations. ## How it works 1. Open **Concepts**. 2. Tick the checkbox on the row(s) you want to update — or use the header checkbox to select the visible page. 3. A floating **Action bar** appears at the bottom of the screen. 4. Choose what to update: - **Source availability** — `available`, `not_set`, or `unavailable` - **Target availability** — applied to one specific market or to all markets at once 5. Confirm. Updates are atomic — either the whole batch succeeds or nothing changes. ## Filtering before selecting Combine bulk select with the **Filters** popover: - Filter by class to update only "Plan" concepts - Filter by availability to flip everything currently `not_set` to `available` - Filter by market to focus on one rollout region ## What gets logged Every batch update is recorded in the [Activity log](/docs/features/activity-log) per concept, so the audit trail stays granular. ## Tips - Use **Market Inspection Mode** (toolbar) to see availability per market in a wide table before bulk-editing. - Pair this with **Approval workflows** to send the freshly-flipped terms to your regional reviewers in a single batch. --- # Market availability > Track term-level readiness across locales with availability statuses. Market availability lets you control the readiness status of each term — both source and target — across your locales. This helps teams track which terms are live, planned, or blocked in each market. ## How it works Market availability is set **per term**, not per concept. Every source term and target term has its own availability status. This gives you granular control: a concept's source term might be "Available" in English, while its Spanish translation is still "Planned". ## Availability statuses | Status | Meaning | |--------|---------| | **Not Set** | Default — no availability decision has been made yet | | **Available** | Live in market — this term is approved and in use | | **Planned** | Coming later — the term exists but isn't live yet | | **Unapproved** | The term exists but hasn't passed governance review | | **Not Available** | Not planned for this market | ## Setting availability When creating or editing a concept: 1. In the **Source Term** card, find the **Market Availability** dropdown 2. Select the appropriate status 3. For each **Target Term**, set its availability independently 4. Save the concept Each term card — source and target — has its own Market Availability selector, so you can track readiness per locale. ## Comparing source and target availability On the **Concept Detail** page, availability badges appear next to each term. This makes it easy to spot mismatches — for example, a source term marked "Available" while a target term is still "Planned" or "Not Set". ## Batch updates You can update market availability for multiple terms at once from the **Concepts** table. Select concepts and use the batch action toolbar to apply a status across all source or all target terms. ## Common patterns **Staged rollout** — Set the source term to "Available" and target terms to "Planned" until translations are reviewed and approved. **Governance hold** — Mark a target term as "Unapproved" when it exists but hasn't passed legal or brand review for that locale. **Deprecation** — Set a term to "Not Available" when it's being retired from a specific market. --- # Locales & markets > Managing locales, source markets, and brand identity per region. Locales define the languages and regions your terminology covers. Each locale can have detailed market definitions that guide how content should sound in that market. ## What is a locale? A locale is a language-region combination identified by a code like `en-us`, `es-es`, or `ar-sa`. Each locale has: | Field | Description | |-------|-------------| | **Code** | Standard locale code (e.g., `de-de`) | | **Name** | Display name in English (e.g., "German (Germany)") | | **Native name** | Display name in the locale's own language (e.g., "Deutsch") | | **Direction** | Text direction — LTR (left-to-right) or RTL (right-to-left) | | **Status** | Active or inactive | ## Adding locales Navigate to **Markets** in the sidebar and click **Add Locale**. Select from the predefined list or create a custom locale code. Your workspace's **source locale** is set in workspace settings and determines which terms are treated as source terms. The source locale is visually distinguished by a badge and cannot be deleted. ## Source market One locale per workspace is designated as the **source market**. This is your primary locale (typically English US) and holds your canonical brand identity — name, tagline, and positioning statement. All other locales are considered target markets. ## Brand identity per locale Each locale can have its own brand identity fields: - **Brand name** — may remain the same or be adapted for the market - **Brand tagline** — localized or retained from the source - **Brand positioning** — market-specific positioning statement These fields appear in the locale detail view and are included in exports. ## Market definitions Each locale can have detailed **market definitions** — structured guidelines covering voice, tone, grammar, cultural conventions, and more. These definitions are what make your ontology actionable for translators and AI agents. → See [Market definitions](/docs/features/market-definitions) for a full guide on the ten sections and best practices. --- # Market definitions > Define voice, tone, grammar, and cultural conventions for each locale. ## What are market definitions? Market definitions are structured guidelines attached to each locale that describe **how** content should sound in that market. They go beyond translation rules to capture voice, cultural expectations, and brand conventions specific to a region. When you open a locale in the **Markets** page and expand the **Market Definitions** panel, you'll find ten structured sections — each designed to give translators, copywriters, and AI tools the context they need to produce content that fits the market. ## The ten sections | Section | What it captures | |---------|-----------------| | **Market Snapshot** | Competitive landscape, audience segments, and market expectations | | **Voice & Locale DNA** | Core personality traits, brand keywords, and anti-patterns for this market | | **Tone & Style Rules** | Sentence structure, active/passive voice, formality level, and preferred patterns | | **Culture & Pragmatics** | Implicit cultural expectations, communication norms, and sensitivity areas | | **Grammar & Mechanics** | Spelling conventions, contractions, sentence length, and punctuation rules | | **UX Microcopy Rules** | CTA patterns, system message tone, error handling, and UI label conventions | | **Locale Conventions** | Currency format, date/time format, number separators, and pricing psychology | | **Terminology Rules** | Preferred and avoided terms specific to this market | | **Golden Examples** | Reference copy — headlines, subheadings, feature descriptions — that exemplify the right tone | | **Output Constraints** | Hard rules: never claim X, always include Y, mandatory disclaimers | Each section is a free-form text field. You can write as little or as much as needed — from a single line to detailed multi-paragraph guidance. ## Editing market definitions 1. Navigate to **Markets** in the sidebar 2. Click the **detail icon** on any locale row 3. Scroll to the **Market Definitions** panel 4. Expand any section and enter your guidelines 5. Click **Save** — changes are stored immediately > Market definitions are workspace-scoped. Each workspace maintains independent definitions per locale. ## Source market vs. target markets Your workspace has one designated **source market** (typically your primary locale, e.g., English US). The source market's definitions capture your canonical brand voice — the baseline that target markets adapt from. Target market definitions describe how to **adapt** that voice for each region. For example: - **Source (en-US)**: Casual, direct, uses contractions, second-person address - **Target (de-DE)**: Formal register, no contractions, third-person where culturally expected - **Target (ja-JP)**: Polite form (です/ます), indirect phrasing, honorific conventions ## How market definitions power AI agents When you sync your ontology to GitHub via **GitHub Sync**, market definitions are exported as structured Markdown files in the `markets/` directory — one file per locale. AI agents (Claude Code, Cursor, custom pipelines) read these files to understand **how** to write for each market. Instead of guessing tone and style, the agent follows your explicit guidelines: ``` ontology/ ├── markets/ │ ├── en-US.md ← Source voice: casual, direct │ ├── de-DE.md ← Formal register, legal disclaimers │ └── pt-BR.md ← Warm, conversational, adapted brand terms ``` This means every AI-generated translation or adaptation follows the same rules your human translators would — without re-briefing. ## Best practices - **Start with Voice & Locale DNA** — This is the most impactful section. Define personality traits, keywords to use, and patterns to avoid. - **Add Golden Examples early** — Concrete examples are more useful than abstract rules. Show what good copy looks like in each market. - **Keep Output Constraints tight** — Use this for non-negotiable rules (legal requirements, brand mandates) that must never be violated. - **Review quarterly** — Markets evolve. Revisit definitions as your product, audience, or regulatory landscape changes. - **Don't duplicate terminology rules** — Term-level governance (preferred/allowed/forbidden variants) belongs in concept terms, not in market definitions. Use the Terminology Rules section for market-wide patterns only. --- # Brand identity per market > Localize your brand name, tagline, and positioning per locale. Brand identity in Black Ice has two layers: 1. **Workspace-level brand** — your default brand name, tagline, and positioning 2. **Per-market overrides** — localized brand expression for each locale ## Setting the workspace default In **Settings → Workspace**, fill in: - **Brand name** — the canonical name (often kept verbatim) - **Brand tagline** — short positioning line shown in marketing - **Brand positioning** — a paragraph capturing the value proposition These default values feed every market unless overridden. ## Per-locale overrides Open **Markets**, click a market row, and the details dialog includes a **Brand identity** section. Enter the localized values: - A localized brand name (only when policy allows — e.g. transliteration into Japanese) - A locale-appropriate tagline (e.g. shorter for German, warmer for Brazilian Portuguese) - A positioning paragraph reflecting cultural pragmatics Empty fields fall back to the workspace default. ## Why this matters The exported ontology bundle includes brand identity per market. AI assistants generating marketing copy use this — together with **Culture DNA** — to produce on-brand output without you re-prompting per region. ## Related - [Locales & markets](/docs/features/locales-and-culture-dna) - [Market definitions](/docs/features/market-definitions) --- # Workspaces > How to collaborate with your team using workspaces, roles, and activity tracking. Workspaces are isolated environments that contain your entire ontology — concepts, terms, relationships, classes, locales, and team members. ## What is a workspace? A workspace is the top-level container for everything in Black Ice. When you sign up, a workspace is automatically created for you. All your data lives within this workspace, and team members you invite share access to the same ontology. ## Workspace settings Each workspace has configurable settings: | Setting | Description | |---------|-------------| | **Name** | The workspace display name | | **Source locale** | The primary language for your source terms (default: English US) | | **Brand name** | Your product or company name | | **Brand tagline** | A short brand description | | **Brand positioning** | Positioning statement used for context in translations | ## Workspace limits by plan | | **Free** | **Pro** | **Builder** | |---|---|---|---| | Workspaces | 1 | 1 | Up to 3 | | Concepts | 50 | 350 | Unlimited | | Markets | 3 | 20 | Unlimited | | Team members | — | — | 10 | ## Creating additional workspaces Builder plan users can create up to 3 workspaces. Navigate to the workspace selector in the sidebar and click **Create Workspace**. Each workspace is fully independent — concepts, classes, locales, and team members are not shared between workspaces. ## Archiving and deleting - **Archive** — Temporarily hides a workspace from the selector. Data is preserved. - **Clear data** — Removes all ontology data (concepts, terms, relationships) while keeping the workspace shell. - **Delete** — Permanently removes the workspace and all its data. This cannot be undone. --- # Team management > Invite team members and manage roles and permissions. Black Ice supports collaborative terminology management with role-based access control. Invite team members and control what each person can do. ## Roles Black Ice has four roles, from most to least permissive: | Role | Capabilities | |------|-------------| | **Owner** | Full control — manage workspace settings, billing, team members, and all data | | **Admin** | Manage team members, create/edit/delete all ontology data | | **Editor** | Create and edit concepts, terms, relationships, and classes | | **Viewer** | Read-only access to all ontology data — cannot create, edit, or delete anything | ## Inviting team members 1. Navigate to **Settings → Team Management** 2. Click **Invite Member** 3. Enter the person's email and select a role 4. Click **Send Invite** The invitee receives a branded email with a link to accept the invitation. If they don't have a Black Ice account, they'll be prompted to create one first. ## Invitation lifecycle - Invitations include a secure token and expiry date - Pending invitations can be re-sent if the original email wasn't received - Once accepted, the team member appears in the workspace with their assigned role - Re-inviting an email address cancels any previous pending invitation ## Changing roles Owners and Admins can change a team member's role at any time from the Team Management settings. ## Removing members Owners and Admins can remove team members. Removing a member revokes their access immediately — their data contributions (concepts, terms) remain in the workspace. ## Viewer restrictions Viewers see a **View Only** banner on restricted pages. All create, edit, and delete actions are hidden from the UI. Direct URL access to protected routes (like create or import pages) redirects viewers back to the concepts list. ## Plan limits Team management is available on the **Builder** plan, which supports up to 10 team members per workspace. --- # Approval workflows > Send terms for external review with shareable approval links. Approval workflows let you send terms for review to stakeholders — legal teams, brand managers, regional experts — without requiring them to have a Black Ice account. ## How it works 1. **Select terms** — Choose one or more terms that need review 2. **Create a request** — Add the reviewer's email, an optional message, and any supporting images 3. **Share the link** — The reviewer receives a unique, time-limited link 4. **Review inline** — The reviewer sees a guided presentation of each term and can approve or reject with comments 5. **Track decisions** — All decisions are recorded with timestamps in the approval history ## Creating an approval request From any concept's detail view: 1. Click **Send for Approval** 2. Select the terms to include 3. Enter the reviewer's email address 4. Add an optional message explaining context 5. Optionally attach images (mockups, screenshots, brand guidelines) 6. Click **Send** ## The reviewer experience Reviewers don't need an account. They click the link and see a step-by-step presentation: 1. **Welcome slide** — Context about what they're reviewing 2. **Identity verification** — Name, email, and role (if required by your settings) 3. **Concept overview** — The concept being reviewed with its description and class 4. **Term details** — Each term with preferred translation, variants, and context 5. **Visual context** — Any attached images 6. **Related concepts** — Semantic relationships for additional context 7. **Decision form** — Approve or reject each term with optional comments ## Approval settings Configure approval behavior in **Settings → Permissions**: | Setting | Description | |---------|-------------| | **Require approver identity** | Reviewers must provide name, email, and role | | **Require role match** | Only specified roles can approve | | **Allowed approver roles** | Which roles are permitted to review | | **Default link expiry** | How long approval links remain valid (default: 30 days) | | **Hide internal notes** | Don't show term notes to external reviewers | | **Hide market availability** | Don't show market constraints to reviewers | | **Hide variant lists** | Don't show allowed/forbidden variants to reviewers | ## Approval history Navigate to **Approval History** to see all past and pending requests, including who reviewed what, when, and their comments. --- # CSV & Excel import > Import terminology from CSV or Excel files with column mapping and conflict resolution. Import existing terminology into Black Ice from CSV or Excel files. The importer handles column mapping, duplicate detection, and conflict resolution. ## Supported formats - **CSV** (.csv) — Comma-separated values - **Excel** (.xlsx) — Microsoft Excel workbooks (first sheet is used) ## Import process 1. Navigate to **Import** in the sidebar 2. Upload your file 3. **Map columns** — Match your file's columns to Black Ice fields (concept name, class, locale, preferred term, etc.) 4. **Preview** — Review the parsed data before importing 5. **Resolve conflicts** — If concepts already exist, choose to skip, overwrite, or merge 6. Click **Import** ## Column mapping The importer auto-detects common column names but lets you manually map any column: | Black Ice field | Common CSV headers | |----------------|-------------------| | Concept name | name, concept, term | | Class | class, category, type | | Description | description, notes, definition | | Locale | locale, language, lang | | Preferred term | translation, target, preferred_term | | Allowed variants | variants, alternatives, allowed | | Forbidden variants | forbidden, blocked, do_not_use | ## Conflict resolution When an imported concept matches an existing one (by name or ID): - **Skip** — Keep the existing concept, ignore the import row - **Overwrite** — Replace the existing concept with the imported data - **Merge** — Add new terms and relationships without modifying existing ones ## Tips - **Include a header row** — The first row should contain column names - **One row per term** — Each row represents one term in one locale for one concept - **Use consistent locale codes** — Match the codes defined in your workspace (e.g., `en-us`, `es-es`) --- # Export formats > Export your ontology as CSV, JSON, or structured ontology formats. Export your ontology in multiple formats, each optimized for different tools and workflows. ## JSON Structured data export for programmatic use and AI tool configuration. **What's included:** - All concepts with their classes and descriptions - All terms with variants, status, and market availability - Semantic relationships between concepts - Market definitions and constraints **Best for:** MCP tool configuration, API integration, TMS import, programmatic access. ## Markdown Human-readable export with clear headings, tables, and structured prose. **What's included:** - Concepts organized by class with descriptions - Terms per locale with preferred term, variants, and status - Market availability overview - Relationship summaries **Best for:** LLM prompts, Gemini, Custom GPTs, internal documentation, knowledge sharing. ## CSV Flat tabular data with configurable columns and two layout options. **Layout options:** - **Translation Grid** — Wide format with one row per concept and markets as columns. Best for spreadsheet review and side-by-side comparison across locales. - **Detailed Rows** — Long format with one row per target term. Best for translation management and per-term filtering. You can configure exactly which columns to include and in what order using the CSV column configurator. **Best for:** Spreadsheets, translators, bulk editing, data review. ## AI Agent Bundle (ZIP) A structured folder of Markdown files with a top-level `CLAUDE.md` entry point, optimized for AI coding agents. **What's included:** - `CLAUDE.md` — Agent entry point with ontology overview and navigation instructions - Per-class folders with concept definitions - Per-locale term files with variants and usage context - Market definitions and relationship data The AI Agent Bundle is designed for the **GitHub Sync → Claude Projects** workflow: sync your ontology to a GitHub repo, then attach it as a Claude Project for context-aware AI assistance. **Best for:** Claude Projects, Claude Code, AI coding agents, developer workflows. ## PDF Prose document with formatted headings, tables, and structured content for document-based AI tools. **What's included:** - Full ontology overview with concepts organized by class - Term tables per locale - Market availability summaries - Relationship descriptions **Best for:** NotebookLM & document-based AI. --- ## Which format should I use? Use this table to find the right format for your tool or workflow: | Tool / Workflow | Recommended Format | |---|---| | **Gemini** | Markdown | | **Custom GPTs** | Markdown | | **Claude Projects** | AI Agent Bundle (ZIP) | | **Claude Code** | AI Agent Bundle (ZIP) | | **NotebookLM** | PDF | | **MCP tools** | JSON | | **Spreadsheet review** | CSV (Translation Grid) | | **Translation management** | CSV (Detailed Rows) | | **API / TMS integration** | JSON | | **Internal documentation** | Markdown or PDF | > **Tip:** If you're using GitHub Sync, the AI Agent Bundle format is automatically optimized for your synced repository structure — making it ideal for Claude Projects and AI-assisted development. --- # Activity log > Audit trail of every change made in your workspace. The Activity Log records every successful in-app change so you can see who did what, when, and to which entity. ## What gets logged - **Concepts** — created, updated, deleted - **Terms** — created, updated, deleted (source and target) - **Classes** — created, updated, deleted - **Relationships** — created, updated, deleted - **Markets** — created, updated, deleted - **Workspace events** — bulk imports, data clears, ownership transfers External actions (approval link clicks, GitHub pushes, exports) are tracked separately. ## Where to find it Open **Activity** from the sidebar. Logs are grouped by day, sorted newest-first, paginated 30 per page. ## Filtering Use the toolbar to filter by: - **Action type** — create, update, delete - **Entity type** — concept, term, class, market, relationship - **User** — see only changes from a specific teammate ## Retention Activity logs are retained for **90 days** then automatically purged. Export or sync to GitHub if you need a longer audit trail. ## Permissions Every workspace member (any role) can view the activity log for workspaces they belong to. Logs are isolated by workspace. --- # Notifications & alerts > Customize what you get notified about and when. Black Ice surfaces in-app notifications for ontology changes, approval activity, and expiring links. You control everything from **Settings → Alert Preferences**. ## In-app notifications Toggle each event independently: - **Concept created / updated / deleted** - **Term created / updated** - **Class changes** - **Relationship changes** The bell icon in the header shows unread notifications and links to the source entity. ## Approval activity - **Approval decisions** — get notified when a reviewer approves or rejects a term - **All terms reviewed** — single summary when an approval request is complete - **Expiring links** — heads-up before an approval link goes stale ## Quiet hours Suppress all in-app notifications during a daily window (e.g. 22:00–08:00). Bundles still queue silently and reappear after the window ends. ## Email digests *(Pro / Builder)* - **Daily digest** — one summary email per day instead of per-event noise - **Approval activity** — email each time a reviewer makes a decision Tier-restricted toggles are visibly grayed out on Free with an upgrade hint. ## Bundle similar notifications Collapse multiple updates to the same entity into one entry (e.g. ten edits to one concept become a single "updated 10 times" item). --- # Permissions & data visibility > Control who can approve and what reviewers see. The **Permissions** panel in Settings (Pro / Builder) gives you fine-grained control over the approval workflow and the data exposed to external reviewers. ## Approval workflow rules - **Require approver identity** — reviewers must enter name, email, and role before deciding (default: on) - **Allowed approver roles** — restrict approvals to a whitelist (e.g. only "Legal", "Brand") - **Auto-approve roles** — terms submitted by trusted internal roles bypass review - **Require role match** — only users whose role matches the approver requirement can decide - **Default link expiry** — how long approval links remain valid (default: 30 days) ## Data visibility on approval pages Hide sensitive fields from external reviewers without altering the underlying data: - **Hide internal notes** — strip notes from the term detail slide - **Hide market availability** — omit availability badges - **Hide variant lists** — drop allowed/forbidden variant arrays These settings apply to every approval link you generate. Existing live links respect the setting at request time. ## Permissions vs. team roles Permissions in this panel govern the **external approval flow**. To restrict who can edit data **inside** the app, see [Team management](/docs/features/team-management). --- # Account & security > Manage your sign-in, password, and account deletion. The **Account** section in Settings is where you manage identity and security. ## Email Your email is set at signup and visible (read-only) in Settings. To change it, contact support — email changes require re-verification. ## Password Click **Change Password** to set a new one. You will be asked for your current password and the new password twice. The new password takes effect immediately and existing sessions stay valid. ## Forgot password From the sign-in screen, click **Forgot password?** to receive a recovery link. Recovery links expire after **7 days**. ## Remember me When signing in, the **Remember me** checkbox persists your session across browser restarts. Without it, the session ends when you close the tab. ## Delete account From Settings → Account → **Delete Account**, you can permanently remove your account. This: - Cascades into all workspaces you own (concepts, terms, markets, classes, custom fields, GitHub configs, approval requests) - Removes you as a member from any workspaces you joined - Frees up your email so it can be re-used to sign up again You will be asked to confirm by typing your email. The action is irreversible. ## Sign-in providers Email + password is supported today. SSO and additional providers are on the roadmap for Builder. --- # Translation policy > Decide what gets translated, what stays in English, and how to override per market. Every class has a **default translation policy** that tells your team (and AI tools) how to handle terminology in target locales. ## The two policies - **Prefer Adapt** — translators should produce a localized version (default for editorial/marketing terms) - **Do Not Translate** — keep the source term verbatim (typical for product names, plan names, brand IP) Policies are part of the structured ontology export, so AI assistants and TMS pipelines can apply them automatically. ## Setting the default at the class level When you create or edit a class, choose its policy. All concepts in that class inherit it. Examples: | Class | Typical policy | |---|---| | Feature | Prefer Adapt | | Plan | Do Not Translate | | ProductLine | Do Not Translate | | MarketingMessage | Prefer Adapt | ## Per-market overrides Some markets need to break the default. From the class detail dialog, open **Market overrides** and set a different policy for one or more locales. > Example: "Plan" is *Do Not Translate* by default, but Brazil legally requires Portuguese plan names — add a `pt-BR → Prefer Adapt` override. ## How AI tools see this When you export the ontology (JSON, ZIP bundle, GitHub sync), each class includes: ```yaml translationPolicy: do_not_translate overrides: pt-BR: prefer_adapt de-DE: prefer_adapt ``` LLM agents reading this bundle will know to render `Pro` as-is in Spanish but adapt it in Brazilian Portuguese — without you writing prompts. --- # Integrations Overview > Connect Black Ice to your AI localization pipeline via GitHub Sync, MCP, REST API, or Workspace API. Compare paths and pick the right one for your team. # Black Ice Integrations — connect your ontology to any AI workflow Black Ice is the **semantic governance layer** for AI localization pipelines. Your ontology — concepts, terminology, market definitions, and relationships — becomes the source of truth that downstream AI systems read from to produce on‑brand, market‑accurate output. This page explains the four ways to connect Black Ice to the rest of your stack and when to pick each one. ## At a glance | Integration | Best for | Tier | Direction | |----------------|-------------------------------------------------------|--------------|----------------| | GitHub Sync | Coding agents (Claude Code, Cursor), CI, repo-based bundles | Builder | Black Ice → Repo | | MCP | Live AI clients (Claude Desktop, Cursor) querying in real time | Builder | Bidirectional | | API Access | Custom AI systems, internal tooling, batch jobs | Pro, Builder | Bidirectional | | Workspace API | External apps with scoped read/write to one workspace | Pro, Builder | Bidirectional | ## GitHub Sync — the recommended default GitHub Sync exports your approved ontology as a structured **Markdown bundle** (`ontology/CLAUDE.md`, `classes/`, `markets/`, `terminology/`, `relationships/`) into a repository you choose. Push on demand or enable auto-sync to update on every change. **Use it when:** - Your AI agent lives in a code repo (Claude Code, Cursor, OpenAI Codex, custom GitHub Actions). - You want your ontology versioned, diff-able, and reviewable through pull requests. - You need a deterministic, auditable artifact that CI can consume. **Why teams pick it first:** no infra to run, native to how engineers already work, and the bundle doubles as documentation. → See [GitHub Sync](/docs/integrations/github-sync) ## MCP — live access for chat clients The Model Context Protocol server exposes your workspace as tools that MCP-compatible clients (Claude Desktop, Cursor) can call directly. Queries hit Black Ice in real time, so there is no export step and no stale data. **Use it when:** - A human is in the loop, asking an AI client questions about terminology, markets, or relationships. - Freshness matters more than versioning. - You want the AI to read *and* propose writes interactively. → See [Connecting MCP clients to Black Ice](/docs/integrations/claude-desktop-mcp) ## API Access — programmatic read/write Generate scoped API keys to read and mutate your ontology from any system. Two endpoints cover most use cases: `query-ontology` for reads and `mutate-ontology` for writes. **Use it when:** - You are building a custom AI system, RAG pipeline, or content generator. - You need to script bulk imports, exports, or migrations. - You want fine-grained, key-scoped access for different services. → See [API Reference](/docs/integrations/api-reference) ## Workspace API — typed external access The Workspace API gives external applications typed read and write access to a single workspace, ideal for product integrations where the consumer is another app rather than an AI agent. **Use it when:** - You are embedding Black Ice data into another product surface. - You want one stable contract per workspace. → See [Workspace API access](/docs/integrations/workspace-api-access) ## Choosing the right path A simple decision tree: ```text Is your AI agent in a code repo or CI? → GitHub Sync Is a human chatting with Claude or Cursor? → MCP Building a custom backend or batch job? → API Access Embedding into another product? → Workspace API ``` Most teams start with **GitHub Sync** because it costs nothing to operate and produces a portable artifact. They add MCP for interactive sessions and the API for custom automation as their pipeline matures. ## Next steps - [Set up GitHub Sync](/docs/integrations/github-sync) - [Connect Claude Desktop or Cursor via MCP](/docs/integrations/claude-desktop-mcp) - [Generate API keys and call the REST endpoints](/docs/integrations/api-reference) - [Use the Workspace API](/docs/integrations/workspace-api-access) --- # GitHub Sync > Push your ontology to GitHub as a structured markdown bundle for AI agents and programmatic consumption. ## Overview Black Ice's GitHub Sync feature pushes your entire approved ontology to a GitHub repository as a structured bundle of Markdown files. This is the primary integration path — no REST API required. Your AI localization pipeline, Claude Code project, or any system with access to the repo can read the ontology directly from the file system or via the GitHub API. ## What gets exported When you sync, Black Ice generates an `ontology/` directory in your repository containing: ``` ontology/ ├── CLAUDE.md # Agent instructions and ontology overview ├── classes/ # One file per concept class │ ├── feature.md │ ├── plan.md │ └── platform.md ├── markets/ # One file per target market │ ├── de-DE.md │ ├── fr-FR.md │ └── ja-JP.md ├── terminology/ # Term definitions per locale │ ├── en-US/ │ ├── de-DE/ │ └── fr-FR/ └── relationships/ # Semantic relationships between concepts └── relationships.md ``` **CLAUDE.md** is the entry point. It tells your AI agent what the ontology contains, how it's structured, and how to use it. **Classes** define the taxonomy — what types of concepts exist (Feature, Plan, Platform, etc.) and their translation policies. **Markets** contain the Culture DNA for each locale — tone of voice, cultural pragmatics, grammar rules, brand identity, and golden examples that guide how content should sound in that market. **Terminology** holds the actual term definitions — source terms, target translations, allowed/forbidden variants, usage context, and approval status. **Relationships** maps how concepts connect to each other semantically (e.g., a Plan *hasFeature* relationships). ## Setting up GitHub Sync 1. Go to **Settings** in your workspace 2. Open the **GitHub Sync** section 3. Enter your GitHub personal access token (with `repo` scope) 4. Specify the repository owner, name, branch, and target path 5. Choose an approval filter — sync all terms, only approved terms, or approved + pending 6. Enable **Auto-sync** to push changes automatically whenever terms are updated ## How AI agents consume the ontology ### Direct file access (Claude Code, Cursor, etc.) If your AI agent runs inside the repo (e.g., Claude Code with a `CLAUDE.md` file), it reads the ontology files directly from disk. No API calls needed. ``` # The agent reads CLAUDE.md first, then navigates the ontology structure # to find the relevant class, market, and terminology files. ``` ### GitHub API consumption External systems can fetch ontology files programmatically via the GitHub API: ```bash # Fetch the agent instructions curl -H "Authorization: token YOUR_GITHUB_TOKEN" \ https://api.github.com/repos/OWNER/REPO/contents/ontology/CLAUDE.md # Fetch a specific market profile curl -H "Authorization: token YOUR_GITHUB_TOKEN" \ https://api.github.com/repos/OWNER/REPO/contents/ontology/markets/de-DE.md # Fetch all terminology for a locale curl -H "Authorization: token YOUR_GITHUB_TOKEN" \ https://api.github.com/repos/OWNER/REPO/contents/ontology/terminology/de-DE/ ``` ### GitHub Actions integration Trigger downstream workflows whenever the ontology is updated: ```yaml # .github/workflows/on-ontology-update.yml on: push: paths: - 'ontology/**' jobs: process-ontology: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Process updated ontology run: | echo "Ontology updated — trigger localization pipeline" # Your pipeline logic here ``` ## Why files, not an API Black Ice deliberately exports Markdown files instead of exposing a REST API because: - **LLMs work better with Markdown** — structured prose is the native input format for language models, not JSON payloads - **GitHub provides the infrastructure** — versioning, access control, branch-based workflows, and webhooks are already solved - **No auth complexity** — your agent reads files from disk or uses an existing GitHub token. No API keys to manage, no rate limits to hit - **Diff-friendly** — every ontology change creates a readable Git diff, making reviews and rollbacks trivial - **Offline-capable** — the ontology works without network access once cloned ## Availability GitHub Sync is available on the **Builder** tier. See [Plans and Pricing](/docs/getting-started/plans) for details. --- # Black Ice + AI: What Your Ontology Unlocks > How Black Ice ontologies power Claude, ChatGPT, Gemini, and local models for governed localization. Black Ice governs meaning. AI scales it. These are not two separate tools — they're a stack. Once your ontology lives in Black Ice, every AI model you connect to it stops guessing and starts reasoning from structured truth. ## Claude ★ Recommended Integration ### Why Claude is the recommended AI for Black Ice Claude's extended context window, instruction-following precision, and native support for structured documents make it the natural partner for ontology-fed workflows. Claude Projects can connect directly to your GitHub repository — the same repo that [GitHub Sync](/docs/integrations/github-sync) pushes your ontology to. This means Claude always reads the latest version of your ontology without manual uploads or re-prompting. Every time you update a concept, approve a term, or refine a market definition in Black Ice, the next Claude session already knows. Claude Code takes this further: it operates directly on your repository, turning your ontology into a live pipeline agent rather than a chat assistant. > **Recommended setup:** Enable GitHub Sync in Black Ice → Connect Claude Projects to the same GitHub repo → Claude always has your latest ontology. No uploads, no re-prompting, no stale context. ### 01 — Market-Specific Content Generation — No TMS Required Connect your Claude Project to the GitHub repo where Black Ice syncs your ontology. Claude now knows your approved terms, market availability rules, brand voice per locale, and forbidden expressions — and it's always current. Ask it to write a landing page for Spain. It doesn't translate — it writes, correctly, from first principles. No briefing doc. No terminology spreadsheet. The knowledge is already there, structured, alive, and automatically updated. > **The difference:** Generic Claude writes fluent Spanish. Ontology-fed Claude writes *your* Spanish — for *that* market. ### 02 — Localization QA That Knows Your Product Feed the ontology to Claude and run it against translated strings. It flags terminology inconsistencies not against a generic dictionary but against your defined concepts — catching the translator who used "Plan Familiar" when your market DNA specifies "Plan Familia," or who left a feature name untranslated that you've explicitly approved as an anglicism. > **The difference:** Rule-based QA checks patterns. Ontology-fed Claude checks meaning. ### 03 — Sprint-Based Delta Localization Your product shipped a new feature. Three concepts changed. You run delta extraction — the ontology surfaces exactly what's new, modified, stable, or deprecated. Claude gets only the delta, with full semantic context, and localizes precisely what changed. Nothing more, nothing less. No re-translation of stable strings. No fuzzy-match guesswork. > **The difference:** Traditional workflows re-translate everything. This one reasons about change. ### 04 — Multi-Project Consistency from a Single Ontology One ontology repo, multiple Claude Projects: marketing copy, developer docs, support content, UI strings. All connected to the same GitHub repository, all reading from the same semantic source. A concept updated in Black Ice syncs to GitHub and propagates to every Claude Project automatically. Consistency isn't enforced by style guides that get ignored — it's structural, it's live, and it's automatic. > **The difference:** Style guides are read once and forgotten. Ontology constraints are active every time Claude runs. ### 05 — Agentic Pipelines with Claude Code Your ontology lives on GitHub. Claude Code reads it, applies market rules, generates localized variants, and commits outputs — no UI, no manual handoffs, no babysitting. The semantic layer is the pipeline's brain. Claude Code is the hands. Three connected layers: Figma (design), GitHub (strings), Black Ice (meaning governance). Claude Code is the agent moving between all three. > **The difference:** You're not prompting a chatbot. You're running a governed localization agent. --- ## ChatGPT / GPT-4o — Supported Integration ### 01 — Custom GPT as a Governed Content Generator Upload your Black Ice ontology export as a knowledge file inside a Custom GPT. Configure the system prompt to reference your terminology rules, market definitions, and tone guidelines. Teams without a technical setup can use this as a governed content interface — no API, no pipeline, just a governed chat window. > **Best for:** non-technical teams who need governed content generation without setting up a pipeline. ### 02 — Terminology Enforcement in Copywriting Flows Paste your ontology's approved term list and forbidden expression list into the GPT-4o system prompt. Use it to review and rewrite marketing copy against your semantic constraints. GPT-4o's instruction-following is strong enough to respect term-level rules in generation tasks, though it requires more explicit prompting than Claude for complex multi-market logic. > **Best for:** single-market, single-project tasks. Multi-market logic needs careful prompt engineering. ### 03 — Structured Translation with JSON Mode Use GPT-4o's JSON mode to generate structured translation outputs that map directly to your ontology's concept IDs. Feed in source strings with ontology context; receive back locale-specific strings with metadata. Useful when building API-based pipelines where output structure matters as much as linguistic quality. > **Best for:** API-based pipelines where output structure is critical. Without JSON mode, output parsing can be fragile. --- ## Gemini — Supported Integration ### 01 — Large-Document Ontology Ingestion Gemini's 1M token context window means you can load your entire Black Ice ontology — concept definitions, market rules, relationship maps, and glossaries — in a single prompt. No chunking, no retrieval logic, no RAG overhead. For very large multilingual ontologies covering dozens of markets and hundreds of concepts, Gemini 1.5 Pro or 2.0 Flash handles the scale comfortably. > **Best for:** large enterprise ontologies where context size would be a constraint with other models. ### 02 — Google Workspace Localization Workflows If your content team lives in Google Docs and Sheets, Gemini's native Workspace integration lets you bring your ontology directly into existing editorial workflows. Load your Black Ice export into a Gemini prompt inside Docs and use it to review or rewrite content against your semantic constraints — without pulling teams out of familiar tools. > **Best for:** teams already embedded in Google Workspace who need governance without workflow disruption. ### 03 — Multimodal Localization QA Gemini's multimodal capabilities allow you to feed screenshots of localized UI alongside your ontology terminology rules and ask it to flag visual string inconsistencies — truncation, untranslated labels, wrong register for the market. Useful for mobile localization QA where the rendered string matters as much as the source string. > **Best for:** UI and mobile localization QA where visual context matters. Unique capability not easily replicated elsewhere. --- ## Local Models (Ollama) — Private Deployment ### 01 — Air-Gapped Terminology Enforcement with Ollama Export your Black Ice ontology as Markdown or JSON and load it into a local model via Ollama — Mistral, LLaMA 3, Phi-3, or Qwen2 all handle structured context reasonably well. The model never leaves your infrastructure. Neither does your terminology. For regulated industries — legal, medical, financial — this is often the only viable route to AI-assisted localization. > **Best for:** regulated industries or any team where data leaving the building is not an option. ### 02 — High-Volume Batch Localization at Zero API Cost Running 50,000 strings through a cloud API gets expensive fast. Running them through a local model with Ollama costs compute, not per-token pricing. Load your ontology once as a system prompt, batch your source strings, and run the pipeline on your own hardware. Quality will be lower than Claude on complex tasks — but for high-volume, lower-complexity string sets with strong ontology grounding, the trade-off is often acceptable. > **Best for:** large-volume, lower-complexity localization where cost per token is a primary constraint. ### 03 — Ontology Drift Detection with Local Embeddings Use local embedding models (nomic-embed-text via Ollama, or similar) to monitor semantic drift in your localized content over time. Run periodic similarity checks between your Black Ice concept definitions and the actual strings in production. No cloud, no API dependency, no data exposure — just a scheduled script and your own infrastructure. > **Best for:** continuous semantic monitoring where the embedding pipeline needs to be fully self-contained. ### 04 — Model Routing: Local for Volume, Claude for Quality The most pragmatic architecture: route high-volume, stable, low-ambiguity strings to a local model for cost efficiency. Route complex, market-sensitive, brand-critical strings to Claude for quality and nuance. Your Black Ice ontology is the shared semantic layer across both. The routing logic lives in your pipeline; the truth lives in the ontology regardless of which model is executing. > **The difference:** The ontology is model-agnostic. The semantic layer doesn't care who's executing — it just enforces the rules. --- ## Integration Comparison | Capability | Claude ★ | ChatGPT | Gemini | Local (Ollama) | |---|---|---|---|---| | Persistent ontology context | ✓ GitHub-linked Projects | ✓ Custom GPTs | ✓ via context | ~ system prompt only | | Auto-updating from GitHub Sync | ✓ Native | ✗ | ✗ | ~ with git pull scripts | | Agentic file & repo operations | ✓ Claude Code | ✗ | ✗ | ~ with custom tooling | | Large ontology ingestion (200k+ tokens) | ✓ | ~ 128k limit | ✓ 1M window | ~ model-dependent | | Multi-market logic in single prompt | ✓ Excellent | ~ Good | ~ Good | ✗ Struggles | | Multimodal UI / screenshot QA | ✓ | ✓ | ✓ Strong | ~ limited models | | Data stays on-premise | ✗ | ✗ | ✗ | ✓ Full control | | Zero API cost at scale | ✗ | ✗ | ✗ | ✓ | | Google Workspace native integration | ✗ | ✗ | ✓ Native | ✗ | | Terminology precision on complex rules | ✓ Best-in-class | ~ Good | ~ Good | ~ Acceptable | | Sprint delta localization pipelines | ✓ Native fit | ~ Possible | ~ Possible | ~ With effort | --- # Connecting MCP clients to Black Ice > Connect Claude Desktop, Claude Code, Cursor, and other MCP clients to your Black Ice workspace to check approved terms and market availability live. Connect Claude Desktop directly to your Black Ice workspace using the Model Context Protocol (MCP). Once connected, Claude can consult your ontology in real time — checking approved terms, flagging forbidden variants in draft translations, and confirming market availability — without you copying anything into the chat. > **What you get in this Phase 1 release.** Seven governance tools, single-workspace per connection, authenticated by API key. OAuth 2.1 (which is required for the public Anthropic Connectors Directory) ships in Phase 2. > **Plan required: Builder.** The MCP integration is part of the Builder plan. Workspaces on Free or Pro can generate API keys for the standard API, but the MCP endpoint will return an upgrade-required error until the workspace is on Builder. ## Before you start You will need: 1. A Black Ice workspace on the **Builder** tier. The MCP endpoint is Builder-only; Free and Pro workspaces will receive an `upgrade_required` error. 2. **Claude Desktop** with custom-connector support enabled in Settings. 3. Five minutes. ## Step 1 — Generate an API key 1. Open Black Ice and go to **Settings → API Access**. 2. Click **Generate API key**, give it a recognisable name (for example, `Claude Desktop — laptop`), and copy the value. 3. The key starts with `bice_…` and is shown **only once**. Paste it somewhere safe before leaving the page. > **Single-tenant, by design.** One key authorises one workspace. If you work across multiple Black Ice workspaces, generate a separate key for each and create a separate Claude Desktop connection per workspace. ## Step 2 — Add Black Ice as a custom connector in Claude Desktop 1. In Claude Desktop, open **Settings → Connectors → Add custom connector**. 2. Use the following configuration: | Field | Value | | --- | --- | | Name | `Black Ice` | | Remote MCP server URL | `https://oosdjmpzvcljxwaqxcko.supabase.co/functions/v1/mcp-server?apikey=YOUR_BICE_KEY` | | Advanced settings | Leave OAuth Client ID and OAuth Client Secret empty | > **Why a URL parameter?** Claude Desktop's custom connector UI does not currently support custom request headers, so the API key travels as a query parameter. Treat the full URL as a secret — anyone with it can read your workspace ontology. Header-based auth (`x-api-key`) remains the recommended path for programmatic clients (curl, MCP Inspector, custom integrations). 3. Save. Claude Desktop will run an `initialize` handshake and discover four tools. ## Step 3 — Try each tool Open a new Claude conversation and try one prompt per tool. The point of each prompt is to demonstrate something that a generic translator would not catch. ### `check_term` — see the governance metadata > _"Use Black Ice to check the approved Spanish (`es-es`) term for **MIDI Editor**. Show me the forbidden variants too."_ Claude will return the approved term, status, market availability, and the `forbiddenVariants` list. The forbidden list is the part that matters: it's the vocabulary your team has explicitly ruled out. ### `validate_translation` — catch a forbidden variant in a draft > _"Validate this Spanish draft against Black Ice: 'El nuevo MIDI Editor permite editar pistas con precisión.' Locale: `es-es`."_ If your workspace marks `MIDI Editor` as a forbidden variant for `es-es` (with `Editor MIDI` as the approved term), Claude will return a `forbidden`-severity flag pointing at the exact span and suggesting the approved replacement. This is the demo moment: the AI being told **"no, not that word."** ### `check_market_availability` — confirm a feature ships in a market > _"Is the **Stem Splitter** feature available for the `es-es` market according to Black Ice? Include any tier or disclaimer constraints."_ Claude will return the availability state (`available`, `planned`, `not_available`, `unapproved`, `not_set`) and any market_constraint metadata you've recorded — tier, disclaimer, local plan name, supported platforms. ### `list_concepts` — discover what's in the ontology > _"Using Black Ice, list all concepts available in `es-es` and tell me which ones are restricted by plan."_ Returns a slim list (`conceptId`, `conceptName`, `className`, `term`, `status`, `availability`) for every concept in the workspace ontology for the locale. Optional `class` filter narrows the list to a single class (`Feature`, `Plan`, `Market`, etc.). Useful as a first call before drilling into a specific concept with `check_term` or `check_market_availability`. ### `list_classes` — discover the workspace taxonomy > _"Using Black Ice, what concept classes exist in this workspace for `es-es`?"_ Returns the distinct class names in the workspace ontology with concept counts, sorted by count descending. Recommended discovery flow: `list_classes` → `list_concepts(locale, class)` → `check_term` or `check_market_availability`. This makes prompts workspace-agnostic — no need to hardcode class names. ### `list_relationships` — traverse the semantic graph > _"Using Black Ice, what concepts are part of `plan_00000001` in `es-es`?"_ Returns semantic relationships (`part_of`, `requires`, `variant_of`, etc.) between concepts. Inputs: `locale` (required), `conceptId` (optional — filter to relationships involving this concept), `direction` (optional — `outgoing`, `incoming`, or `both`; default `both`), `relationshipType` (optional — case-insensitive filter like `part_of`). Recommended graph traversal flow: `list_concepts(locale, class)` → pick a `conceptId` → `list_relationships(locale, conceptId)` to discover what it depends on, includes, or is part of. ### `get_market_profile` — voice, tone, and culture DNA for a locale > _"Using Black Ice, what's the voice and tone profile for `es-es`?"_ Returns the full market profile for a locale: brand identity (name, tagline, positioning) plus the 10-section culture DNA — Market Snapshot, Voice/Locale DNA, Tone & Style Rules, Culture & Pragmatics, Grammar & Mechanics, UX/Microcopy Rules, Locale Conventions, Terminology Rules, Golden Examples, and Output Constraints. Use this to ground translation and content generation in the same market definition that drives Black Ice's in-app workflows. Input: `locale` (required, e.g. `es-es`). Returns `{ found: false }` if the locale is not configured for the workspace. ## How disambiguation works If a concept name resolves to more than one concept (for example, two classes both have a "Studio" concept), the tool returns: ```json { "ambiguous": true, "matches": [ { "conceptId": "feat_00000007", "conceptName": "Studio", "className": "Feature" }, { "conceptId": "plan_00000003", "conceptName": "Studio", "className": "Plan" } ], "hint": "Multiple concepts share that name. Re-call this tool with the conceptId from `matches`." } ``` Claude will follow up with the `conceptId` directly, bypassing name matching entirely. ## Troubleshooting **"Missing or invalid x-api-key header"** — the connector URL is missing the `?apikey=bice_…` parameter, or the value doesn't start with `bice_`. Re-check the Remote MCP server URL. **"No concept matched 'X' for locale 'Y'"** — either the concept doesn't exist in your workspace or no target term has been created yet for that locale. Check **Concepts** in Black Ice and confirm the locale has been added under **Markets**. **Claude isn't suggesting Black Ice tools.** Add a system instruction to your Claude Project: _"When the user asks about a translation, terminology decision, or market availability, call Black Ice first."_ **Forbidden variant not flagged.** Only target terms with `status: approved` enforce. Pending or draft terms are ignored on purpose so in-progress edits don't generate noise. Approve the term in Black Ice and try again. **Wrong workspace.** Each `bice_` key is bound to one workspace. If Claude returns the wrong terms, you've connected the key for a different workspace — generate a new key in the correct workspace. ## What's next - **Phase 2** adds OAuth 2.1 + Dynamic Client Registration so Black Ice can be listed in the Anthropic Connectors Directory and connected with one click. - **Phase 3** wraps the write API (`mutate-ontology`) so Claude can propose new terms or flag drift directly into your workspace pending approval. ## Other MCP clients The endpoint is transport-agnostic Streamable HTTP and works with any MCP client. Claude Desktop is walked through above because its custom-connector UI cannot send custom headers, so the API key has to ride in the URL. Other clients should pass the key via the `x-api-key` header instead: - **Claude Code** — `claude mcp add black-ice --transport http --header "x-api-key: bice_…"` - **Cursor** — add an MCP server in settings, point it at the endpoint, set `x-api-key` as a custom header. - **MCP Inspector** — `npx @modelcontextprotocol/inspector` and configure the same endpoint + header. - **Custom SDK clients** — any TypeScript or Python MCP SDK client; just include the `x-api-key` header on every request. Both auth paths (`?apikey=` query param and `x-api-key` header) are accepted by the server. Use the header form whenever your client supports it — it keeps the key out of URL logs. --- # API Reference > Read and write your workspace ontology programmatically — endpoints, auth, schemas, and a downloadable full reference. The Black Ice API lets external tools — Claude Code, AI agents, scripts, or CI pipelines — read and write your workspace ontology programmatically. It's the same data layer the Black Ice UI uses, exposed over HTTPS with key-based authentication. ## What you can do - **Read** the full ontology (concepts, terms, classes, relationships, markets, brand identity) as a single JSON document - **Write** in batches: create, update, delete, or upsert concepts, terms, relationships, classes, and market constraints - **Sync** terminology from external systems (TMS, PIM, CMS) without leaving your tool of choice ## Endpoints | Method | Endpoint | Purpose | |---|---|---| | `GET` | `/functions/v1/query-ontology` | Export the full workspace ontology | | `POST` | `/functions/v1/mutate-ontology` | Apply a batch of write operations | Base URL: `https://oosdjmpzvcljxwaqxcko.supabase.co` ## Authentication Every request must include the header `x-api-key: bice_xxxxxxxx`. Generate a key from **Settings → API Access** in the app. Keys are scoped to a single workspace. ## Tier & limits - **Pro tier or higher** is required (writes need Pro/Builder) - **Reads:** 60 requests/min per key - **Writes:** 30 requests/min per key, max 50 operations per request - Bidirectional relationships are auto-mirrored server-side — no need to insert both directions ## Quick example ```bash curl --header "x-api-key: bice_YOUR_KEY_HERE" \ "https://oosdjmpzvcljxwaqxcko.supabase.co/functions/v1/query-ontology" ``` ## Full reference The complete reference covers every entity (concept, term, relationship, class, market_constraint), all actions (create / update / delete / upsert), field-level schemas, error codes, and worked examples — including a section of best practices for AI agents. 📥 Download full API reference (Markdown) > 💡 **Tip for Claude Code users:** drop `BLACK_ICE_API.md` into your project's context folder. Claude can then call the API directly with the right schemas, IDs, and bidirectional handling already understood. --- # Workspace API access > Read and write your ontology programmatically from external tools. The Workspace API lets external AI tools, scripts, and integrations interact with a workspace without going through the GitHub bundle. > Workspace API access is included on **Pro** and **Builder** plans. ## Generating an API key 1. Open **Settings → API Keys**. 2. Click **Create API key**, give it a label (e.g. `production-llm`). 3. Copy the key shown — it is displayed **once**. The hashed value is stored; you cannot retrieve it later. 4. Store the key in your tool's secret manager. ## Endpoints The two main endpoints are deployed under your project's edge function URL: - `POST /functions/v1/query-ontology` — read the ontology (concepts, terms, relationships, markets) - `POST /functions/v1/mutate-ontology` — create, update, or delete concepts and terms ## Authentication Send your API key in the `Authorization` header: ``` Authorization: Bearer bk_live_xxxxxxxxxxxxxxxx ``` Each request is scoped to the workspace that owns the key. Last-used timestamps are recorded so you can rotate stale keys. ## Rate limits - Read endpoints: 60 requests/minute per key - Write endpoints: 30 requests/minute per key - Payload cap: 1 MB per request Exceeding either returns `429 Too Many Requests` with a `Retry-After` header. ## When to use API vs. GitHub Sync - **GitHub Sync** — best for one-way distribution to LLM tooling, CI/CD pipelines, and Claude Code-style agents that consume Markdown. - **Workspace API** — best for two-way integrations: a custom dashboard, an internal QA bot, or a TMS connector that needs to push approved terms back into Black Ice. ## Revoking a key Click the trash icon next to a key in **Settings → API Keys** to revoke it. Active integrations using that key will start receiving `401 Unauthorized` immediately. ---