AI

AI in Holarch is optional assistance for systems engineering work: answering questions about the open project, rewriting and generating requirements, proposing functions and flows, suggesting trace links, drafting risks, test cases, trade study criteria and decision rationale, and drawing clipart. Everything else in Holarch works without AI.

Every AI change is shown as a preview first. Nothing changes in the model until you confirm, and one undo (⌘Z) reverses the whole change.

Concepts

How to use it

When and why

AI helps at each stage of the lifecycle, but it never replaces review:

• Requirements: turn vague statements into singular, measurable "shall" statements; split compound requirements; draft rationale; generate child requirements; judge Correct, Feasible and Necessary.
• Behavior: extract functions from a requirement set and suggest a functional flow (after requirements, before allocation).
• Traceability: suggest missing links and flag doubtful ones in the Traceability Matrix.
• Verification: draft a test case for a requirement.
• Risk and decisions: draft risks for an item, suggest trade study criteria from requirements and MOEs, and draft decision rationale.
• Documents and whiteboards: summarize or translate a document, rewrite rich text, and turn sticky notes into requirements.
• Questions: ask about the project (“Which requirements have no verifying test case?”) or about Holarch (“How do I import a CSV of requirements?”).

Set up AI

On the Free plan, AI needs a key from your own account with a provider, or your organization's key. Paid plans include AI tokens, so no key is needed.

1. Create an API key in the provider's console: Anthropic Console, OpenAI Platform, Google AI Studio, or your Azure OpenAI resource.
2. In Holarch, click your initials → Account Settings and scroll to AI keys, or choose ✦ AI ▾ → AI Settings….
3. Click + Add Key.
4. Choose the Provider and paste the key into API key. For Azure OpenAI, also enter the Endpoint (https://<resource>.openai.azure.com) and the Deployment name.
5. Optional: enter a Monthly limit (tokens) of at least 1,000. Leave it empty for no limit.
6. Click Test and Save. Enter your password if Holarch asks for it (Confirm Your Password; the check lasts 10 minutes). Result: Holarch sends a short test request. When it works, the key is saved and the toast says “AI key added (Anthropic API, …abcd).” When the test fails, the key is not saved and the message says why.
7. Check Key in use. It now reads Your key: Anthropic API (…abcd).

Use an AI tool

1. Open the page and select the item, for example a requirement in a document.
2. Click ▾ next to ✦ AI in the top bar (or press ⌘K and type the tool's name).
3. Choose the tool, for example Make Measurable…. Result: a busy dialog shows “Asking <provider>…” with a running timer. Cancel stops the request.
4. Review the preview. Edit the suggestion where the dialog allows it. Untick anything you do not want.
5. Click the apply button (Apply, Add Selected, Create Test Case, Apply Selected and so on). Result: the change is applied as one undo step, with a short toast such as “Make Measurable applied”.

Ask a question

1. Click ✦ AI in the top bar (or ⌘K → Ask AI…).
2. Type a question and press Enter (Shift+Enter adds a line), or click one of the examples. Result: the answer appears in the panel. Names of items and help topics are links; some answers include a button that opens the page the answer refers to.
3. Ask follow-up questions; the recent conversation is sent with each question.
4. ⟲ clears the conversation; ⚙ opens AI Settings; × closes the panel.

Worked example: tightening EO-1 requirements

The CubeSat EO-1 demo has three Draft requirements that a reviewer would reject: 2.5 Safe Mode Recovery (“The spacecraft should recover from safe mode quickly and resume imaging as appropriate”), 3.5 Battery Thermal Control (“The thermal design shall keep the battery warm enough (TBD).”) and 6.4 Operator Interface (“The operator interface shall be user friendly and/or easy to use.”).

1. Create the demo (Manage Projects → Project Files ▾ → Create Demo Project) and open EO-1 System Requirements Specification.
2. Select 2.5 Safe Mode Recovery and choose ✦ AI ▾ → Make Measurable…. Result: the preview shows Current, Changes and Suggested (editable before applying), for example “The spacecraft shall exit safe mode and resume imaging within 24 hours of the fault being cleared.”, with an explanation that 24 hours is a proposed value.
3. Change the value if your mission analysis says otherwise, then click Apply.
4. Select 6.4 Operator Interface and choose Split into Singular Requirements…. The preview lists each singular requirement; item 1 replaces 6.4 and the others are added after it. Click Apply Split.
5. Select 3.5 and choose Draft Rationale…. Review the rationale and Apply.
6. Open Needs & Requirements → Quality, then ✦ AI ▾ → AI Quality Review (n requirements)…. The review judges Correct, Feasible and Necessary for each requirement with a reason. Approved requirements start unticked. Click Apply Selected.
7. With 2.5 still selected, choose Generate Test Case…. Review Description (ordered steps), Set Up, Expected Result and Verification Method, then Create Test Case. The test case is created and linked to 2.5.

Each step is one undo. Press ⌘Z to reverse any of them.

Tips and good practice

• Treat AI output as a draft. Check numbers, units and assumptions against your analysis before applying. Values the AI proposes are marked in its explanation.
• Select first. Requirement tools appear in ▾ only when a requirement (or another statement) is selected.
• Ticked means applied. Read each preview row. Changes to Approved, baselined or locked items, link removals and suggestions with web addresses start unticked and highlighted; tick them only after checking.
• Watch the input banner. When the input included text from an imported file, another person's changes, an AI reference file or hidden text, the preview shows a banner. Check those suggestions closely.
• Keep reference packages small. Reference files are added to many prompts and use more of your tokens.
• Set a monthly limit on keys you share with an organization.

Common mistakes:

How it connects to other features

• AI changes go through the normal model: they are undoable, saved, shared live with collaborators and recorded in version history.
• Requirement tools feed the Quality page (manual Yes/No values with “AI: …” reasons), traceability (generated requirements traced to their target), verification (generated test cases with the verification method label) and the risk register (generated risks related to their cause).
• Ask AI uses the Help topics and a list of the features in the running app, so it says when something is not available.
• Organization admins control AI for their projects (see Administration).

The ✦ AI control

The control sits in the top bar of every project page. ✦ AI opens Ask AI. ▾ lists the AI tools of the current page, then AI Settings…. Pages without AI tools show only ✦ AI. In narrow windows it shows as the sparkle and ▾. The same tools are in ⌘K under AI tools for this page.

The control is off, with the reason in its tooltip, when:

• you have view-only access: “View only: AI tools need edit access”;
• no key is available: “Add an AI key in Account → AI keys” (▾ stays available for AI Settings…);
• the project's organization turned AI off: “AI is turned off for this organization by its administrator.”

Every AI feature

Tones for Change tone… and Insert AI Content…: Academic, Assertive, Casual, Confident, Constructive, Empathetic, Exciting, Fluent, Formal, Friendly, Inspirational, Professional.

For the page-specific details, see Help: Functional Analysis, Traceability Matrix, Trade Studies, Risk Register, Whiteboards and Whiteboard Clipart.

Previews and approval

• Nothing is applied until you confirm. Closing or cancelling a preview changes nothing.
• One undo step. Each applied AI change is a single undo step, however many items it touches.
• Opt-in for protected items. Changes to Approved, baselined (in a document baseline) or locked items, link removals (Functional Analysis reassignments, Suspect Assist) and suggestions that contain a web address are highlighted and start unticked. Single changes show a box such as “Apply this change anyway (…)”.
• Input banner. The preview shows a banner when the input included text from an imported file, another person's changes, an AI reference file or hidden text.
• Checked replies. Every reply is checked before you see it. A reply with the wrong shape, too much text or ids that were not in the request is rejected (“The AI response was rejected…”), and nothing changes. Text is cleaned for where it goes: no scripts, images, frames or links to other sites.
• Ask AI shows text. Only links to Holarch pages and help topics are clickable; web addresses stay plain text.

See How AI Handles Untrusted Content for how project text is kept separate from instructions.

AI keys

Providers

Every key form also has Monthly limit (tokens) (empty for no limit; at least 1,000 and at most 10,000,000,000).

Your keys

The list under Your keys (Account Settings → AI keys, and AI Settings) shows for each key: Provider (with Preferred when you have keys for several providers), Key (the last 4 characters, and Rejected at last use when the provider refused it), Added by, Last used, This month (tokens, “of” the limit, and Limit reached), and the buttons:

• Test sends a short request: “✓ Works (1.2 s)” or “✕” with the reason.
• Remove asks “Remove the … key ending in …? Your requests then use your organization's key, if there is one.” and needs a recent password check. Toast: “AI key removed.”

One key per provider: adding a key for a provider that already has one replaces it. Your first key is the preferred one.

With no key: “You have no key of your own.”

Organization keys

Org admins add, test and remove the organization's keys on the Account page under Organizations → Organization keys, with the same form. “Members of … without their own key use this key.” Members see only which organization keys exist (“Organization keys: Anthropic API (…abcd). Used when you have no key of your own.”). With none: “No organization key. Members without their own key cannot use AI.”

Usage this month by member lists Member, Requests, Tokens and Cost (estimate) with a Total row.

Which key is used

The server picks one key for each request, in this order:

1. Included AI tokens on Individual and Team plans and during a trial, until this month's tokens are used up.
2. Your organization's key: the key of the project's organization when you are a member of it; outside such a project, the key of your organization when you belong to exactly one. An organization that turned AI off lends its keys to no one.
3. Your own key, when there are no included tokens left and no organization key applies.
4. None: AI features are off. Key in use reads “None. AI features are off until a key is added.”

Key in use in AI Settings and on the Account page shows the result, for example Your key: Anthropic API (…abcd) or Organization key of SYSE 682: OpenAI API (…wxyz).

Included AI tokens

Included tokens reset each month and do not carry over. When they are used up, AI uses your organization's key if one applies, then your own key if you added one, or stops until the next month. Requests made with your own key do not count against the included tokens; your provider bills you for them. Included AI uses Anthropic (Claude models). Additional fair-use limits may apply.

A typical request uses 5,000 to 40,000 tokens, so 1 million tokens covers roughly 50 to 100 everyday AI actions such as Ask AI, a quality review or drafting requirements.

AI Settings

Open with ✦ AI ▾ → AI Settings…, ⚙ in Ask AI, ⌘K → AI Settings…, or your initials → AI Settings….

Save keeps the settings (“AI settings saved”).

AI reference files

Reference files add background material, such as a standard or a statement of work, to AI prompts.

• File types: .txt .md .csv .json .xml .html .docx .reqif. Up to 200,000 characters are kept per file.
• The active package is added to Ask AI and to the generate, expand, test case, risk, summary, insert-content and rich-text tools.
• Packages are kept in this browser, per project. They are not shared with other members. “Reference files are too large for browser storage.” means the browser refused to store them; remove files.

Usage and limits

Months are calendar months in UTC. Org admins see usage by member on the Account page; site admins see totals and the top users on Admin → Usage.

Organization AI switch

An org admin can turn AI off for every project of the organization with Allow AI in this organization's projects (see Administration). While it is off:

• every AI request for those projects is refused on the server, also with a member's own key;
• the organization's keys are not used by anyone;
• the ✦ AI control in those projects is off with “AI is turned off for this organization by its administrator.”

A project belongs to an organization when one of its owners chooses it under Share → Organization.

Privacy: what is sent

• Only on request. Nothing is sent to an AI provider unless you start an AI feature.
• Only what the feature needs. For a requirement tool: the requirement, its parent, its verifiers and the project name. For Ask AI: the question, a description of Holarch's features, up to three help topics, the project's entities and relationships, the current page and the recent conversation. The active AI reference package is added where listed above.
• Hidden text is left out. Zero-size, invisible or white-on-white text is not sent.
• Where it goes. From the Holarch server to the provider of the key in use (Anthropic, OpenAI, Google or your Azure OpenAI resource), under that provider's terms. Check the provider's terms, including whether it keeps or trains on API data. Holarch does not use your content to train AI models.
• What Holarch keeps. No prompt text and no replies. For each request it records the time, the key, the task, the number of tokens, the estimated cost and the result, for usage and limits. Ask AI conversations stay in your browser only when Remember previous prompts is on.
• Keys. Keys are encrypted on the server, never sent back to the browser and never shown again after saving.
• Data you must not store. Holarch is not approved for Controlled Unclassified Information, export-controlled technical data (ITAR or EAR) or classified information. Do not store such material in projects or send it to AI. See Data You Must Not Store Here.

Shortcuts

Messages

Limits

• One key per provider per account and per organization.
• Monthly key limits: 1,000 to 10,000,000,000 tokens.
• 30 requests per minute and 3 at a time per person.
• Prompts up to 600,000 characters; replies up to 400,000 characters.
• Reference files: up to 200,000 characters each, stored in this browser.
• Generate Requirements: 1–20 parents and 0–10 children per parent. Expand Requirements: 1–20. Generate Risks: up to 3 per run. Clipart: 1–8 variants.
• Viewers cannot use AI.

Related pages

• Administration
• Your account
• Collaboration
• Help: Ask AI and AI Tools, AI Settings and Keys, Add an AI Key, Which AI Key Is Used, AI Usage and Limits, How AI Handles Untrusted Content