Skip to content
v1.0
AI

Proposals & provenance

The assistant never acts. It proposes, the proposal is visibly provisional, a person accepts, and the acceptance is what gets recorded — with their name on it.

The proposal

Add a front setback rule

6 m to the primary frontage for a dwelling house in the Low–medium density residential zone, citing Table 5.5.5.1.

Adds one rule to the Eastvale ruleset and records a job against your name. Nothing is published until you run a bake.

Three signals, each surviving without the others: the dashed edge (shape), the mark (origin), and the provenance line (words). Colour is deliberately not one of them — it is the signal that does not survive greyscale, a colourblind reader, or forced-colours mode.
Code 
<GdAiProposal
  title="Add a front setback rule"
  accept-label="Add to the ruleset"
  provenance="Adds one rule to the Eastvale ruleset and records a job against your name. Nothing is published until you run a bake."
  @accept="apply"
  @discard="dismiss"
>
  <p>6 m to the primary frontage, citing Table 5.5.5.1.</p>
</GdAiProposal>

Sources — and what was withheld

2 sources, 3 withheld
  • Eastvale Planning Scheme 2019 v9.2ruleset · 209 provisions
  • Project layers4 layers, 12,481 shapes

Not shown to the assistant, so the answer above does not account for it:

  • State aerial imageryall rights reserved
  • AEC boundarieswithin your organization only
  • Council parcel extract (2024)no licence recorded
Terra's gateway runs redact() over the context, drops any source whose licence forbids disclosure, and NAMES what it held back. That naming exists so the interface can show it — an interface that swallows it turns a deliberate exclusion into an invisible one.
Code 
<GdAiSources :sources="SOURCES" :withheld="WITHHELD" />

The distinction matters to a planner in a way it would not elsewhere. "No canopy figure" and "a canopy figure the assistant was not permitted to read" are different answers to the same question, and only one of them means go and look yourself.

API

GdAiProposal

Props

PropTypeDefault
titlerequiredstring—

What is being proposed, in a few words — "Add a setback rule".

provenancerequiredstring—

What accepting will DO, and where it will be recorded. Required, and required to be concrete: "Adds one rule to the Eastvale ruleset and records a job against your name", never "Applies the change".

state"open" | "accepted" | "discarded""open"

The settled forms stay in the thread rather than disappearing — a conversation you can no longer audit is not a record. Both drop the dashed edge, because the thing is no longer provisional.

acceptLabelstring"Accept"

The word on the accepting button. "Accept" is rarely the best one — say what will happen.

generatingboolean—

The model is still writing the proposal's body.

busyboolean—

The acceptance is in flight.

Events

acceptvoid

The person accepted. The component does NOT write — what gets recorded, against which ledger, with whose name on it, is product policy. In Terra it is a job in the ledger, not a chat message.

discardvoid

The person declined. Keep the proposal in the thread in its discarded state.

GdAiSources

Props

PropTypeDefault
sources{ label: string; origin?: string; to?: string }[][]

The inputs the model was given. NOT planning citations — a citation carries an instrument, a ref and a verification status, and is rendered by the product's own provision components.

withheld{ label: string; reason: string }[][]

What the licence layer refused to pass to the model, and why in the licence's own terms. Terra's redact() names what it held back precisely so this can be shown.

Usage Guidelines

Do

  • Require a provenance string that explicitly states the outcome of accepting the proposal.
  • Preserve resolved proposals in the UI thread for auditability, updating their state rather than removing them.
  • Explicitly expose withheld sources. If the system drops a source due to permissions, it must be listed in the withheld prop.

Don't

  • Don't allow autonomous mutation. The AI should propose changes via this component, and a human user must explicitly accept them to record the action.
  • Don't style "Accept" as an AI action. Accepting is a standard user action. The AI mark should only denote the origin of the proposal.
  • Don't confuse sources with planning citations. The GdAiSources component displays model inputs, not verified planning instruments.

Behavior & Anatomy

Anatomy of a Proposal

A provisional state is communicated through three independent signals to ensure accessibility:

  • Shape: A dashed border indicates the content is provisional.
  • Mark: The GdAiMark explicitly attributes the content to the model.
  • Provenance: A text explanation of the action's consequence.

Navigate

Esc