Proposal: Practical Knowledge Base and Ontology Workflow¶

Superseded by docs/proposals/vocabulary-consolidation.md (2026-07-10), which carries this document's gap analysis and §A next-best-action design forward as VC-1 … VC-16.

Historical document — terminology no longer applies. This proposal was drafted before the 2026-05-28 terminology consolidation. The words "knowledge base", "linkml_schema", "KB policy", "field mapping", etc. that appear below are retired in the current codebase. See docs/proposals/terminology.md for the authoritative vocabulary (Vocabulary / Concept / Concept Scheme / Binding / Field Binding / LinkML Schema). The behaviour described here is preserved verbatim for historical context only.

Status: Draft (historical) Date: 2026-05-18 Scope: PyCharter knowledge base, ontology, semantic governance, and agent-ready context workflow

Historical snapshot — preserved as-is. This proposal predates the Branch D Wave 1 API rename (2026-05-20) and references URLs in their pre-rename form. The canonical paths the rest of the docs use are listed in ../reference/url-migration-map.md.

Executive Summary¶

PyCharter already has strong semantic ingredients: concept schemes, concept types, relationships, field bindings, semantic health, extraction, suggestions, provenance, governance, SHACL validation, reasoning, and context packs. The current challenge is not lack of primitives. The challenge is that the primitives do not yet form one obvious, highly usable workflow.

The target product workflow should be:

Import data and knowledge assets.
Normalize them into an inventory.
Generate semantic suggestions.
Review and approve suggestions.
Bind approved concepts to contract fields.
Measure semantic health and governance readiness.
Serve governed context to humans, APIs, and agents.

This proposal recommends turning the ontology/knowledge-base layer into a guided "semantic workbench" centered on a single user journey:

Import assets -> suggest concepts -> review -> approve -> bind fields -> measure coverage -> serve governed context.

The goal is to make PyCharter's ontology layer useful to data stewards, data engineers, analysts, and agent developers without requiring them to understand every internal semantic subsystem up front.

Product Thesis¶

PyCharter's contract layer answers:

What shape should this data have, and is this record valid?

PyCharter's ontology/knowledge-base layer should answer:

What does this data mean, where is that meaning used, who approved it, and how can systems safely consume it?

The value of this layer is not simply "a knowledge graph." The value is practical governance and usability:

A user can import schemas, contracts, docs, DDL, CSVs, and code.
PyCharter can suggest business concepts and relationships.
A steward can approve or dismiss those suggestions.
Contract fields can be bound to approved concepts.
The organization can measure semantic coverage and quality.
Downstream tools and agents can retrieve trusted context with provenance.

Current Assessment¶

What Exists Today¶

The current codebase includes many of the right building blocks:

Concept schemes and ontology models.
Concept graph models and editor APIs.
Relationship types and concept types.
Field-to-concept binding models.
Semantic search, lineage, discovery, and health modules.
Extraction and KB ingest flows that populate a governed suggestion queue.
Suggestion accept/dismiss APIs.
Governance proposals, reviews, and tier concepts.
SHACL governance validation.
OWL/RDF-style reasoning for inferred relationships.
Context packs for token-efficient agent use.
UI surfaces for ontology, suggestions, concepts, lineage, configuration, and the unified editor.

Main Gaps¶

The primary gaps are workflow cohesion, persistence consistency, and user clarity:

The user journey is not obvious enough.
Users can see many semantic capabilities, but the "next best action" is not always clear.
The standalone knowledge-base UI is deprecated.
The future appears to be the unified editor, but the product shape should be made explicit.
Some KB management pieces are still Phase 1/in-memory.
KB versioning, cross-KB links, and lineage records currently need durable persistence before they can be considered production-ready.
Search and discovery are useful but basic.
Current search is largely text/ILIKE style.
Discovery is heuristic and should be upgraded into a ranked suggestion system with evidence.
Governance and review are spread across modules.
Suggestions, proposals, semantic health, review, and mapping lifecycle need one unified reviewer experience.
The agent-facing path is promising but incomplete.
Context packs exist, but they need stronger policy, evidence, version, and source-freshness metadata.
The mental model needs simplification.
Users should not need to distinguish "linkml_schema", "knowledge base", "concept graph", "semantic store", "field binding", "scheme", and "context pack" before accomplishing a basic task.

Target Users¶

Data Steward¶

Primary goals:

Curate business concepts.
Approve definitions and mappings.
Maintain semantic quality.
Prevent drift in core/domain concepts.

Needs:

Suggestion inbox.
Approval workflow.
Impact analysis.
Semantic coverage dashboard.
Clear ownership and review state.

Data Engineer¶

Primary goals:

Import schemas/contracts.
Bind fields to concepts.
Validate contracts and pipelines.
Understand lineage and downstream impact.

Needs:

Import wizard.
Field mapping workbench.
Contract semantic health.
Clear API/CLI equivalents.
Batch operations.

Domain Owner¶

Primary goals:

Review domain-specific concepts.
Confirm definitions and relationships.
Understand how their domain data is represented.

Needs:

Low-jargon review screens.
Side-by-side source evidence.
Simple approve/request-changes decisions.
Ownership notifications.

Analyst or Agent Developer¶

Primary goals:

Find trusted business definitions.
Retrieve certified context.
Understand which fields/metrics are approved.
Use semantic context in analysis or agents.

Needs:

Search and browse.
"What does this mean?" API.
Context pack API.
Provenance/evidence metadata.

Platform Admin¶

Primary goals:

Configure governance policies.
Manage namespaces, tiers, and permissions.
Monitor system health.

Needs:

Policy configuration.
Audit logs.
Migration tooling.
Operational dashboards.

Design Principles¶

1. One Primary Workflow¶

The product should present one primary workflow:

Import -> Suggest -> Review -> Bind -> Measure -> Serve.

Secondary features should attach to this journey rather than appear as separate islands.

2. Progressive Disclosure¶

The UI should start with practical language:

"Business term"
"Field mapping"
"Review suggestion"
"Coverage"
"Where used"

More technical vocabulary can appear as needed:

Concept scheme
RDF
SHACL
OWL reasoning
Context pack

3. Evidence Beside Every Suggestion¶

Every suggestion should show why it exists:

Source asset.
Matched field/document/code span.
Confidence.
Similar existing concepts.
Existing mappings that influenced the suggestion.
Potential duplicates.
Governance tier.

4. Reversible and Auditable Actions¶

Approving, dismissing, remapping, and deprecating should create durable audit history. Users should be able to see:

Who changed it.
What changed.
Why it changed.
Which source evidence supported it.
Which contracts or fields were affected.

The home screen should be organized around work states:

Assets imported.
Suggestions pending.
Concepts needing definitions.
Fields unmapped.
Mappings awaiting approval.
Governance gates failing.
Context packs ready to serve.

6. UI and API Should Mirror Each Other¶

Every UI workflow should have an equivalent API/CLI path. This is important for:

CI workflows.
Automated ingest.
Agent integrations.
Enterprise deployment.

7. Agent Readiness Comes From Human Governance¶

Agent-facing context should be an output of the governed workflow, not a separate unreviewed path. Agents should consume approved concepts, field bindings, context packs, and evidence envelopes.

Proposed User Workflow¶

Step 1: Create or Select a Domain Workspace¶

User intent:

I want to manage semantic meaning for a domain.

UI behavior:

User selects or creates a domain workspace.
Workspace maps to a concept scheme or set of schemes.
User sees domain summary:
concept count
mapped fields
unmapped fields
pending suggestions
coverage score
recent activity

Backend needs:

Durable scheme/domain metadata.
Clear relationship between domain, concept scheme, contracts, imported assets, and governance policies.

Implementation notes:

Use existing concept schemes as the underlying semantic grouping.
Add a higher-level "semantic workspace" if needed, but avoid duplicating concept-scheme responsibility unless there is a clear need.

Step 2: Import Assets¶

User intent:

I want PyCharter to inspect my contracts, schemas, docs, DDL, or code and find possible business concepts.

Supported inputs:

Existing PyCharter contracts.
JSON Schema.
DDL.
CSV.
dbt manifests.
Markdown/RST/PDF/HTML docs.
JSON/YAML files.
Source code via tree-sitter adapters.
Pipeline metadata and run outputs.

UI behavior:

Import wizard asks:
What are you importing?
Which domain/scheme should this feed?
Should suggestions be generated automatically?
Which policy applies?
Who should review?
On completion, user sees:
source count
extracted concept count
extracted relationship count
duplicates detected
failures/skipped files
link to suggestion inbox

Backend needs:

Durable ingest run table.
Durable imported asset table.
Per-source provenance.
Extractor result persistence.
Suggestion queue integration.

Current code to build on:

pycharter.semantic.kb.ingest
semantic KB ingest routes
extraction adapters
suggestion materializer

Step 3: Normalize Inventory¶

User intent:

I want to know what PyCharter found before I approve anything.

UI behavior:

Show imported assets in an inventory:
contracts
schemas
tables
fields
documents
code artifacts
pipelines
Each asset shows:
source URI
source type
last imported time
fingerprint/hash
linked contract, if any
extraction status
generated suggestions

Backend needs:

Asset identity and fingerprinting.
Reingest detection.
Source-to-suggestion links.
Source-to-contract links.

Implementation notes:

Do not let suggestions float without source context.
Every concept or relationship candidate should point back to an imported asset and extraction run.

Step 4: Generate Suggestions¶

User intent:

I want PyCharter to propose concepts, relationships, and field mappings that I can review.

Suggestion types:

New concept suggestion.
Duplicate/merge suggestion.
Relationship suggestion.
Field binding suggestion.
Definition improvement suggestion.
Deprecation suggestion.
Mapping confidence upgrade suggestion.

UI behavior:

Suggestions inbox grouped by:
domain/scheme
source asset
suggestion type
confidence band
governance tier
reviewer
Each suggestion has:
proposed action
source evidence
confidence
conflicting/duplicate concepts
impact preview
accept/dismiss/request-change actions

Backend needs:

Suggestion scoring model.
Suggestion evidence model.
Duplicate detection.
Batch accept/dismiss.
Review notes and dismissal reason.
Idempotent suggestion generation.

Implementation notes:

Current suggestion queue is the correct control point.
Enhance it rather than creating a second queue.

Step 5: Review and Approve¶

User intent:

I want to decide which concepts and mappings should become trusted.

Review states:

pending
accepted
dismissed
needs_changes
superseded
merged

Mapping states:

unmapped
suggested
mapped
approved
technical_only

UI behavior:

Reviewer sees a focused queue with keyboard-friendly bulk operations.
The review screen shows:
source evidence
proposed concept/mapping
existing similar concepts
affected contracts/fields
governance tier
policy requirements
Accepting a suggestion materializes it into:
concept graph
relationship graph
field binding registry
contract semantic metadata, if applicable

Backend needs:

Durable review decision events.
Reviewer identity.
Approval requirements by tier.
Merge gate result storage.
Mapping lifecycle events.

Implementation notes:

Keep "suggestion acceptance" and "formal proposal merge" aligned.
Lightweight/free tier suggestions can be accepted directly.
Domain/core changes should route through proposal/review gates.

Step 6: Bind Concepts to Contract Fields¶

User intent:

I want my contract fields to point to approved business concepts.

UI behavior:

Mapping workbench shows:
contract schema on one side
concept graph/glossary on the other
suggested mappings between them
coverage progress
invalid/deprecated mapping warnings
Users can:
accept suggested mapping
search concepts
create local/free concept
request new domain/core concept
mark a field as technical-only
add annotation concepts
mark relationship such as references, derived_from, same_as

Backend needs:

Canonical field binding persistence.
Versioned mapping history.
Contract write-back or contract-side binding projection.
Mapping lifecycle events.
Validation against concept registry.

Implementation notes:

Treat field bindings as the bridge between data contracts and ontology.
Avoid making users edit raw YAML for common mapping tasks.

Step 7: Measure Semantic Health¶

User intent:

I want to know whether this domain is semantically usable and governed.

Health dimensions:

Field coverage.
Required concept definitions.
Deprecated concept usage.
Invalid concept references.
Relationship validity.
Unreviewed suggestions.
Unapproved mappings.
Governance gate failures.
Source freshness.
Owner/steward completeness.

UI behavior:

Show health at multiple levels:
domain
contract
concept
field
imported asset
Provide actionable issue lists:
"12 required fields unmapped"
"3 mappings reference deprecated concepts"
"5 suggestions need domain owner review"
"2 concepts have no definition"

Backend needs:

Semantic health service.
Stored health snapshots.
CI-friendly route.
Threshold configuration.

Implementation notes:

Health should produce actions, not just percentages.
Every failed check should link to the exact screen where the user can fix it.

Step 8: Serve Governed Context¶

User intent:

I want applications and agents to retrieve trusted semantic context.

Consumers:

PyCharter UI.
PyGubernator agents.
Data catalog/search APIs.
CI checks.
Analyst notebooks.
External MCP clients.

Outputs:

Context packs.
Certified concept definitions.
Field binding summaries.
Contract semantic summaries.
Lineage/explanation responses.
Evidence envelopes.

Backend needs:

Context pack snapshots.
Evidence envelope shape.
Policy-aware context retrieval.
Stable context IDs/hashes.
API/MCP tools.

Implementation notes:

Context packs should include source, version, policy, quality, and provenance metadata.
PyCharter should mint the evidence.
Agent runtimes should carry and persist it.

Proposed Information Architecture¶

Primary UI Areas¶

1. Semantic Home¶

Purpose:

Single landing page for the domain/scheme.

Shows:

Coverage score.
Pending suggestions.
Concepts needing review.
Mappings needing approval.
Recent ingest runs.
Governance blockers.
Quick actions:
Import assets
Review suggestions
Open mapping workbench
Run health check
Preview context pack

2. Import Wizard¶

Purpose:

Bring assets into the semantic workflow.

Steps:

Select source type.
Upload/paste/connect source.
Select target scheme/domain.
Configure extraction policy.
Preview extractable assets.
Run import.
Review ingest summary.

3. Suggestions Inbox¶

Purpose:

Central review queue.

Views:

By source.
By concept.
By confidence.
By governance tier.
By reviewer.

Actions:

Accept.
Dismiss.
Request changes.
Merge duplicate.
Create proposal.
Batch accept low-risk items.

4. Concept Workbench¶

Purpose:

Edit and understand concepts.

Shows:

Definition.
Type.
Tier.
Owner.
Relationships.
Slots.
Source/provenance.
Where used.
Review history.
Inferred relationships.

5. Mapping Workbench¶

Purpose:

Bind contract fields to concepts.

Shows:

Contract schema/fields.
Suggested mappings.
Concept search.
Mapping status.
Relationship editor.
Coverage bar.

6. Semantic Health¶

Purpose:

Make semantic quality measurable and actionable.

Shows:

Coverage.
Errors.
Warnings.
Governance blockers.
Trend over time.
CI result summary.

7. Context Preview¶

Purpose:

Show what an agent/API would receive.

Shows:

Context pack.
Evidence envelope.
Contract version.
Source URIs.
Policy decision.
Quality/freshness state.

Surgical UI/UX Enhancement Plan¶

The UI/UX work should be surgical. The goal is not to create a new product shell or a separate knowledge-base application. The goal is to make the existing unified editor feel like a clear semantic workflow.

Governing constraint:

Build on the existing editor shell, workspace store, canvas, left panel, inspector, toolbar, modal, tabs, and semantic components. Do not introduce a parallel design system or a standalone KB page.

UI/UX Principles¶

1. Preserve the Existing Editor Mental Model¶

Use the current editor structure:

Left panel: navigation, assets, filters, queues, import entry points.
Main canvas/workspace: graph, contract/schema views, mappings, visual relationships.
Right inspector: selected item details, actions, metadata, provenance, governance state.
Bottom companion panel: logs, activity, health issues, review notes, context preview.
Toolbar: mode/layer controls, save, import, review, health, export.

Do not add a new top-level "knowledge base" app unless the unified editor cannot reasonably support a view. The existing deprecated standalone knowledge-base page should remain deprecated.

2. Rename Concepts in the UI Before Rebuilding Screens¶

Use accessible labels in primary UI surfaces:

Internal term	User-facing label
concept	Business term
concept scheme	Domain vocabulary
field binding	Field mapping
semantic health	Coverage and readiness
suggestion	Review item
context pack	Agent context preview
provenance	Source evidence

Formal names can remain in tooltips, details panels, and API docs.

3. Make Status Visible Everywhere¶

Every concept, field mapping, suggestion, and imported asset should visibly answer:

Is this reviewed?
Is this approved?
Is this stale?
Is this blocked by governance?
What should the user do next?

Use existing badge patterns where possible:

pending
suggested
mapped
approved
dismissed
needs_changes
deprecated
technical_only

4. Use Existing Component Families¶

Prefer extending existing UI modules:

components/editor/*
components/semantic/*
components/editor/shell/*
components/editor/toolbar/*
stores/editor/*
lib/api/semantic.ts
lib/api/knowledgeBase.ts

Avoid creating another component tree under components/knowledge-base/* for new work unless it is being migrated into components/editor/*.

5. Make Review Actions Fast¶

The review workflow should support:

Batch accept.
Batch dismiss.
Keyboard-friendly list navigation.
Filter chips.
Source/evidence preview.
Inline confidence and governance status.
Clear "why this suggestion exists" panel.

6. Do Not Over-Decorate¶

PyCharter is an operational data tool. UI changes should be dense, quiet, and work-focused:

No marketing-style hero sections.
No decorative gradients/orbs.
No oversized cards.
No nested cards inside cards.
No new color palette unless it extends existing tokens.
Prefer icons and compact labels in toolbars.
Use tables/lists/split panes for review and mapping workflows.

UI/UX User Journey: Revenue Agent Readiness¶

A high-value common use case is preparing a revenue analytics domain for safe AI-agent use.

Scenario:

A SaaS company wants an internal AI analyst agent to answer questions such as:

"What drove the change in net revenue retention this quarter?"
"Which customer segments have the highest expansion revenue?"
"Which subscriptions are active, paused, churned, or trialing?"

The company already has useful assets, but they are scattered:

A warehouse schema with tables like customers, subscriptions, invoices, and payments.
A dbt manifest with model descriptions and column metadata.
A YAML data contract for the revenue mart.
A Markdown glossary maintained by finance.
A few informal notes about how "ARR", "MRR", "active customer", and "churned customer" should be interpreted.

The value of PyCharter's KB layer is that it turns those scattered assets into reviewed business terms, governed field mappings, health checks, and agent-ready context. The agent should not guess what net_revenue, recognized_revenue, invoice_amount, or subscription_status mean. It should receive approved context with evidence.

Journey Overview¶

Primary user:

Maya, a data steward responsible for revenue definitions.

Supporting users:

Devon, a data engineer responsible for data contracts and warehouse mappings.
Priya, a finance domain owner responsible for approving revenue terminology.
An AI platform engineer responsible for exposing governed context to an internal analyst agent.

The journey should feel like a guided operational workflow, not an ontology modeling exercise.

High-level flow:

Maya opens the semantic home view inside the existing editor.
She imports the revenue contract, dbt manifest, warehouse schema, and finance glossary.
PyCharter extracts candidate terms, fields, relationships, and evidence.
Maya reviews suggestions from a split-pane inbox.
Devon maps contract fields to approved business terms in the mapping workbench.
Priya approves sensitive terms and definitions.
Maya runs semantic health checks and fixes remaining coverage issues.
The AI platform engineer previews the exact context an agent will receive.
The team publishes a governed revenue context pack.

Screen-by-Screen Experience¶

1. Semantic Home: "What needs attention?"¶

Maya starts in the existing editor shell. She does not have to choose between a graph editor, ontology editor, and separate knowledge-base page.

The first view shows a compact revenue workspace summary:

Domain vocabulary: Revenue.
Source assets: 4 imported.
Review items: 37 pending.
Field mappings: 62 percent covered.
Health: 8 blocking issues, 14 warnings.
Agent context: not ready.

Primary actions are presented as compact toolbar or panel actions:

Import assets.
Review suggestions.
Open mapping workbench.
Run health check.
Preview agent context.

The user value is immediate orientation. Maya knows the current state and the next best action in under 10 seconds.

2. Import Entry Point: "Bring in what we already have"¶

Maya clicks Import assets from the toolbar or left panel. A modal or side drawer opens inside the editor.

She selects:

Source type: data contract.
Source type: dbt manifest.
Source type: warehouse schema.
Source type: Markdown glossary.
Target vocabulary: Revenue.

After import, PyCharter shows an import summary instead of throwing her straight into a graph:

42 candidate business terms found.
118 fields discovered.
31 candidate field mappings found.
9 possible duplicate terms found.
12 suggestions require domain-owner approval.
5 extraction warnings.

The summary links directly to the Suggestions Inbox. The canvas state remains intact.

The user value is reduced setup friction. PyCharter starts from artifacts the team already trusts.

3. Suggestions Inbox: "Review meaning with evidence"¶

Maya opens the review queue. The UI uses a split-pane layout:

Left: review items with type, proposed label, confidence, source, status, and owner.
Right: selected suggestion details, evidence, duplicate candidates, impact preview, and actions.

Example selected suggestion:

Proposed business term: Monthly Recurring Revenue.
Source: finance glossary, line reference.
Related fields: mrr, monthly_recurring_revenue, subscription_mrr.
Confidence: high.
Governance: finance approval required.
Proposed action: create concept and map three candidate fields.

Maya can:

Accept the term.
Edit the label or definition.
Dismiss it as duplicate.
Route it to Priya for approval.
Batch accept low-risk synonyms.

The UI should keep formal ontology details out of the primary workflow. Maya sees "business term", "source evidence", and "field mapping", while RDF/SHACL details remain in expandable technical sections.

The user value is trust. Suggestions are not magical because every proposed change shows why it exists.

4. Mapping Workbench: "Bind terms to real fields"¶

Devon opens the Mapping Workbench from the same editor shell.

The layout is intentionally operational:

Left panel: contract fields grouped by object or table.
Center workspace: current mappings and relationship view.
Right inspector: selected field, candidate concepts, evidence, actions.
Bottom panel: coverage and health issues.

For revenue_mart.subscription_status, Devon sees suggested business terms:

Subscription Status.
Active Subscription.
Customer Lifecycle Status.

The inspector shows:

Current contract field description.
Candidate concept definition.
Source evidence.
Existing mappings using the same concept.
Warnings if the concept is deprecated or unapproved.

Devon chooses Subscription Status, sets the relationship as represents, and approves the mapping. Coverage updates immediately.

The user value is practical adoption. A data engineer can complete mappings without editing YAML manually or navigating a separate ontology tool.

5. Domain Approval: "Approve sensitive definitions"¶

Priya receives or opens a filtered queue of terms requiring finance approval.

She sees concise review cards:

Term.
Proposed definition.
Source evidence.
Fields affected.
Reports or context packs affected.
Required action.

For "Net Revenue Retention", she can approve the definition, request changes, or mark the term as restricted. If she requests changes, the item moves back to the review queue with the reason attached.

The user value is governance without forcing domain owners into technical tooling. Priya can make approval decisions from evidence and impact, not from ontology syntax.

6. Semantic Health: "What still blocks readiness?"¶

Maya runs a health check from the toolbar.

The health panel shows actionable issues:

Blocking: 17 revenue fields are unmapped.
Blocking: "ARR" and "Annual Recurring Revenue" appear as possible duplicates.
Warning: 4 mapped fields use unapproved concepts.
Warning: one context pack includes a stale source asset.

Each issue row has a fix action:

Open mapping.
Open duplicate review.
Request approval.
Re-run import.
Mark technical-only.

The user value is a clear path to readiness. Health is not a score alone; it is a task list with navigation.

7. Agent Context Preview: "What exactly will the AI see?"¶

Before exposing the revenue domain to an AI analyst agent, the AI platform engineer opens Preview agent context.

The preview shows:

Included business terms.
Included field mappings.
Source assets and evidence references.
Approval and policy status.
Excluded unresolved or unapproved items.
Approximate token count.
Context pack ID and content hash.

Example preview excerpt in the UI:

Monthly Recurring Revenue: approved, finance-owned, mapped to 3 fields.
Subscription Status: approved, mapped to revenue_mart.subscription_status.
Net Revenue Retention: approved with finance policy note.
invoice_amount: excluded from revenue-agent context because it is unmapped.

The engineer can copy the context pack ID or call the HTTP/Python API with the same ID.

The user value is agent safety. The team can see exactly what will be sent before an agent uses it.

8. Published Outcome: "Agent-ready governed meaning"¶

At the end of the journey, the Revenue workspace shows:

Review queue: 0 blocking items.
Field mapping coverage: above target threshold.
Health: no blocking issues.
Context pack: ready.
Latest source assets: current.
Approval history: complete.

Now an AI analyst agent can retrieve the approved revenue context pack before answering questions. If the underlying contract or glossary changes, PyCharter can mark impacted concepts, mappings, and context packs as stale.

The user value is not just documentation. It is an operational control plane for business meaning.

Why This Journey Shows Tremendous Value¶

This use case is valuable because revenue analytics is high-stakes, cross-functional, and full of ambiguous terms. It is exactly the kind of domain where AI agents can sound confident while using the wrong field or definition.

The KB workflow helps by:

Turning existing contracts, schemas, dbt metadata, and glossaries into one reviewed semantic workflow.
Making suggested business terms explainable through evidence.
Letting data engineers bind approved meaning to real fields.
Letting domain owners approve definitions without learning ontology tooling.
Giving AI engineers a stable, inspectable context artifact.
Creating an audit trail for every accepted concept, mapping, and context pack.
Making drift visible when source assets change.

From a UI/UX perspective, the product should feel like:

A guided readiness workflow for business meaning, field mappings, and AI context.

It should not feel like:

A blank ontology editor where users must model everything from scratch.

The practical promise is simple: before an AI agent answers revenue questions, PyCharter helps the team prove which terms, fields, definitions, and evidence the agent is allowed to rely on.

Proposed UI Changes by Surface¶

A. Editor Landing / Semantic Home¶

Current opportunity:

Users need one place to understand semantic workflow state.

Surgical change:

Add a semantic summary panel inside the existing editor/dashboard area.
Do not create a new landing page.
Reuse existing editor dashboard layout patterns.

Content:

Domain vocabulary selector.
Coverage and readiness summary.
Pending review count.
Unmapped field count.
Failed health issue count.
Recent import runs.
Primary actions:
Import assets.
Review suggestions.
Open mapping workbench.
Run health check.
Preview agent context.

Acceptance criteria:

User can identify the next action in under 10 seconds.
Summary links deep-link into existing editor tabs/panels.
No new top-level navigation item is required beyond existing ontology/editor routes.

Likely files:

src/pycharter/ui/src/components/editor/shell/EditorDashboard.tsx
src/pycharter/ui/src/components/editor/shell/EditorLeftPanel.tsx
src/pycharter/ui/src/lib/api/semantic.ts

B. Import Entry Point¶

Current opportunity:

Ingest exists, but users need a guided entry point.

Surgical change:

Add an Import action to the existing editor toolbar and/or left panel.
Use a modal or side drawer, not a full new page.
Reuse existing dialog/modal styling.

Flow:

Choose source type.
Upload/paste/select source.
Select domain vocabulary.
Configure extraction options.
Run import.
Show import summary.
Link to generated review items.

Acceptance criteria:

Existing ingest endpoints remain usable.
Import does not disrupt current canvas state.
Import summary can be reopened from recent activity.

Likely files:

components/editor/toolbar/UnifiedEditorToolbar.tsx
components/semantic/IngestGraphModal.tsx
lib/api/semantic.ts

C. Suggestions Inbox¶

Current opportunity:

Suggestions exist, but the review experience should become the workflow center.

Surgical change:

Improve the existing suggestions queue rather than building a new queue.
Add split-pane review: list on the left, detail/evidence on the right.

List columns:

Type.
Proposed label/action.
Confidence.
Source.
Tier.
Status.
Reviewer/owner.

Detail panel:

Proposed change.
Source evidence.
Duplicate candidates.
Impact preview.
Governance requirements.
Actions: accept, dismiss, request changes, create proposal.

Acceptance criteria:

Reviewer can approve/dismiss without navigating away.
Batch actions are available for selected rows.
Every suggestion shows evidence.

Likely files:

components/semantic/SuggestionsQueue.tsx
components/semantic/SuggestionsPanel.tsx
app/ontology/suggestions/page.tsx
lib/api/suggestions.ts

D. Mapping Workbench¶

Current opportunity:

Field mappings are the heart of the workflow but should be easier to complete visually.

Surgical change:

Add a mapping tab/panel within the editor shell.
Use existing schema/contract canvas and concept assets instead of a new mapping UI shell.

Layout:

Left: contract fields, grouped by object/table.
Center: current canvas or compact mapping list.
Right: concept search, selected concept details, mapping actions.
Bottom: coverage/issues panel.

Actions:

Accept suggested mapping.
Search and bind concept.
Approve mapping.
Remap concept.
Mark field technical-only.
Add annotation concept.
Add relationship type.

Acceptance criteria:

User can map a field in three actions or fewer.
Coverage updates immediately after mapping changes.
Invalid/deprecated concepts are blocked or clearly warned.

Likely files:

components/editor/shell/WorkspaceInspectorTabs.tsx
components/editor/inspectors/*
components/editor/bindings/*
stores/editor/workspace-concept-mutators.ts
lib/editor/concept-binding.ts

E. Semantic Health Panel¶

Current opportunity:

Health should be actionable, not just a metric.

Surgical change:

Add a health/issues panel to the existing companion panel or dashboard.
Keep it list-based and compact.

Issue row fields:

Severity.
Target type.
Target name.
Rule/check.
Short message.
Fix action.

Fix actions:

Open field mapping.
Open concept.
Open suggestion.
Run validation.
Create proposal.

Acceptance criteria:

Every issue has a target and a fix path.
Health panel can filter by contract, concept, severity, and owner.
CI health result and UI health result use the same response shape.

Likely files:

components/editor/shell/EditorCompanion.tsx
components/semantic/KBPolicyCard.tsx
components/editor/shell/BottomPanelTabs.tsx
lib/api/semantic.ts

F. Concept Detail / Workbench¶

Current opportunity:

Concept detail should become the source of truth for business meaning.

Surgical change:

Enhance existing concept inspector/detail routes.
Add collapsible sections, not a full redesign.

Sections:

Definition and aliases.
Type/tier/owner.
Relationships.
Slots/attributes.
Mapped fields.
Suggestions and review history.
Source evidence.
Inferred relationships.
Context preview.

Acceptance criteria:

User can answer "where is this used?" from concept detail.
User can see whether a concept is approved or deprecated.
User can open related mappings and suggestions directly.

Likely files:

app/editor/concepts/[conceptKey]/*
components/editor/shell/ConceptInspector.tsx
components/editor/shell/ConceptLineagePanel.tsx
components/editor/shell/InferredRelationshipsPanel.tsx

G. Context Preview¶

Current opportunity:

Context packs are agent-facing, but users need to inspect what will be sent.

Surgical change:

Add a context preview panel under concept, contract, and field details.
Treat it as a read-only preview with copy/export actions if needed.

Shows:

Included concepts.
Included fields.
Source evidence.
Governance/policy status.
Approximate tokens.
Content hash/context ID.

Acceptance criteria:

User can preview agent context before exposing it to agents.
Preview includes evidence and policy status.
Preview can be generated without mutating the graph.

Likely files:

components/editor/shell/EditorCompanion.tsx
components/semantic/ConceptOriginCard.tsx
lib/api/semantic.ts

UI/UX Implementation Phases¶

UX Phase 0: Inventory and Guardrails¶

Tasks:

ID	Task	Priority
UX0-001	Audit current semantic/ontology screens and mark each as keep, merge, deprecate, or internal.	High
UX0-002	Document existing component patterns to reuse: badges, tables, dialogs, panels, inspector sections, tabs.	High
UX0-003	Confirm all new workflow surfaces live inside the unified editor path.	High
UX0-004	Define shared status labels and badge colors using existing tokens.	Medium
UX0-005	Add feature flags for new import/review/mapping/health panels if rollout risk is high.	Medium

UX Phase 1: Semantic Home and Import Entry¶

Tasks:

ID	Task	Priority
UX1-001	Add semantic summary panel to editor dashboard.	High
UX1-002	Add Import action to toolbar/left panel.	High
UX1-003	Adapt existing ingest modal into a guided import flow.	High
UX1-004	Add import summary state and recent import list.	Medium
UX1-005	Add empty states for "no assets", "no suggestions", and "no mappings".	Medium

UX Phase 2: Review Inbox¶

Tasks:

ID	Task	Priority
UX2-001	Convert suggestions queue into split-pane review layout.	High
UX2-002	Add evidence and duplicate-candidate sections to suggestion detail.	High
UX2-003	Add batch selection and actions.	High
UX2-004	Add filters for status, type, confidence, tier, and source.	High
UX2-005	Add "create proposal" route for governed suggestions.	Medium

UX Phase 3: Mapping Workbench¶

Tasks:

ID	Task	Priority
UX3-001	Add field mapping panel/tab inside editor shell.	High
UX3-002	Add concept search and bind flow.	High
UX3-003	Add suggested mapping acceptance flow.	High
UX3-004	Add coverage bar and unmapped field list.	High
UX3-005	Add mapping history timeline in inspector.	Medium

UX Phase 4: Health and Context Preview¶

Tasks:

ID	Task	Priority
UX4-001	Add semantic health issue panel.	High
UX4-002	Add fix-link navigation from issue to concept/field/suggestion.	High
UX4-003	Add context preview panel.	Medium
UX4-004	Add evidence envelope display for context preview.	Medium
UX4-005	Add visual regression and workflow walkthrough tests.	High

UI/UX QA Checklist¶

Before each UI/UX phase is considered done:

No new standalone KB page is introduced.
Existing editor layout remains intact.
New screens reuse existing buttons, badges, tabs, panels, dialogs, and typography.
The longest labels fit in desktop and mobile/tablet widths.
Loading, empty, error, and permission-denied states exist.
All primary actions have success and failure feedback.
No visible UI text describes implementation details.
Keyboard and focus behavior works for dialogs and review actions.
Screens are verified with browser screenshots.
The old route remains compatible or is explicitly marked deprecated.

Backend Architecture¶

The workflow should be implemented as a set of durable registries and services.

Core Registries¶

Asset Registry¶

Stores imported assets:

asset_id
workspace/domain/scheme
source_uri
source_type
source_fingerprint
imported_at
imported_by
parser/extractor used
linked contract_id, if any
status

Ingest Run Registry¶

Stores each ingest execution:

ingest_run_id
actor
target scheme
source count
success/failure counts
extraction config
started_at/ended_at
generated suggestion count
logs/errors

Concept Registry¶

Already largely exists through concept schemes and concept graph tables.

Needs:

clearer lifecycle status
owner/steward fields
review status
source/evidence summary

Mapping Registry¶

Stores field-to-concept bindings:

mapping_id
contract_id
contract_version
field_path
concept_id
binding_kind: primary or annotation
state
confidence
source_suggestion_id
approved_by
approved_at
created_at/updated_at

Suggestion Registry¶

Build on the existing governed suggestion queue.

Enhance with:

suggestion_type
evidence records
confidence score
duplicate candidates
impact preview
reviewer assignment
policy requirements
decision events

Health Registry¶

Stores health snapshots:

health_run_id
target type: domain, contract, concept, field
target id
coverage metrics
error/warning counts
issue list
created_at

Context Registry¶

Stores context pack/evidence snapshots:

context_pack_id
target concept/contract/field/query
generated_at
token budget
included concept IDs
included field IDs
source evidence IDs
policy decision
content hash

Consolidated Public API¶

PyCharter should expose one clean semantic workbench API over the existing primitives. The current modules can remain internally separated, but users should not need to know which subsystem owns imports, suggestions, mappings, health, governance, context packs, or provenance.

Recommended design:

A Python facade for scripts, notebooks, tests, CLI commands, and in-process apps.
A resource-oriented HTTP API for the UI, remote services, CI, and agents.
A small set of shared request/response models used by both surfaces.
Compatibility shims for existing endpoints during migration.

The public API should map directly to the workflow:

Workspaces -> Assets -> Imports -> Suggestions -> Concepts -> Mappings -> Health -> Governance -> Context.

Python API Proposal¶

Package Shape¶

Recommended public namespace:

from pycharter.semantic.workbench import SemanticWorkbench

Optional convenience export:

from pycharter.semantic import SemanticWorkbench

Recommended modules:

pycharter.semantic.workbench
pycharter.semantic.models
pycharter.semantic.client
pycharter.semantic.errors

The facade should provide a cohesive API over internal services:

from pycharter.semantic import SemanticWorkbench

kb = SemanticWorkbench.connect("sqlite:///pycharter.db")

workspace = kb.workspaces.get_or_create(
    key="finance",
    title="Finance Semantic Workspace",
)

run = kb.imports.ingest(
    path="./examples/finance",
    workspace="finance",
    actor="alice",
    generate_suggestions=True,
)

suggestions = kb.suggestions.list(
    workspace="finance",
    status="pending",
    confidence="high",
)

for suggestion in suggestions.items:
    kb.suggestions.accept(
        suggestion.id,
        actor="finance-steward",
        reason="Matches approved glossary",
    )

kb.mappings.bind(
    contract_id="finance/orders",
    contract_version="1.2.0",
    field_path="orders.net_revenue",
    concept_id="finance:NetRevenue",
    actor="finance-steward",
    state="approved",
)

report = kb.health.run(
    target_type="workspace",
    target_id="finance",
)

context = kb.context.build(
    concept_id="finance:NetRevenue",
    purpose="agent_context",
    token_budget=2000,
)

Facade Services¶

The SemanticWorkbench object should expose typed service properties.

kb.workspaces
kb.assets
kb.imports
kb.suggestions
kb.concepts
kb.mappings
kb.health
kb.governance
kb.context

Each service should be narrow, predictable, and typed.

`workspaces`¶

Purpose:

Manage the user-facing semantic domain boundary.
Backed by concept schemes unless a separate workspace model is created.

Recommended methods:

kb.workspaces.create(key, title, description=None, owner=None)
kb.workspaces.get(key)
kb.workspaces.get_or_create(key, title=None)
kb.workspaces.list()
kb.workspaces.summary(key)

`assets`¶

Purpose:

Track imported source assets and their provenance.

Recommended methods:

kb.assets.list(workspace=None, source_type=None, contract_id=None)
kb.assets.get(asset_id)
kb.assets.refresh(asset_id, actor=None)
kb.assets.delete(asset_id)

`imports`¶

Purpose:

Run extraction/ingest and produce suggestions.

Recommended methods:

kb.imports.ingest(
    path,
    workspace,
    actor=None,
    adapter=None,
    recursive=True,
    generate_suggestions=True,
    use_cache=True,
)
kb.imports.ingest_text(filename, content, workspace, actor=None, adapter=None)
kb.imports.get(run_id)
kb.imports.list(workspace=None, status=None)

Return model:

ImportRun(
    id: str,
    workspace: str,
    status: str,
    assets_seen: int,
    assets_imported: int,
    suggestions_created: int,
    failures: list[ImportFailure],
)

`suggestions`¶

Purpose:

Review, accept, dismiss, and explain generated semantic suggestions.

Recommended methods:

kb.suggestions.list(
    workspace=None,
    status=None,
    suggestion_type=None,
    confidence=None,
    source_asset_id=None,
    limit=100,
)
kb.suggestions.get(suggestion_id)
kb.suggestions.accept(suggestion_id, actor, reason=None)
kb.suggestions.dismiss(suggestion_id, actor, reason)
kb.suggestions.request_changes(suggestion_id, actor, comment)
kb.suggestions.batch_accept(ids, actor, reason=None)
kb.suggestions.batch_dismiss(ids, actor, reason)

Important model fields:

Suggestion(
    id: str,
    suggestion_type: str,
    status: str,
    confidence: float,
    proposed_action: dict,
    evidence: EvidenceEnvelope,
    impact: ImpactPreview,
)

`concepts`¶

Purpose:

Manage concepts, schemes, relationships, and where-used views.

Recommended methods:

kb.concepts.search(query, workspace=None, concept_type=None, limit=20)
kb.concepts.get(concept_id)
kb.concepts.create(workspace, concept_key, name, concept_type=None, tier="free")
kb.concepts.update(concept_id, **patch)
kb.concepts.deprecate(concept_id, actor, replacement_id=None)
kb.concepts.relationships(concept_id, direction="both", inferred=False)
kb.concepts.where_used(concept_id)

`mappings`¶

Purpose:

Bind contract fields to approved concepts and manage lifecycle state.

Recommended methods:

kb.mappings.list(contract_id=None, concept_id=None, workspace=None, state=None)
kb.mappings.suggest(contract_id, workspace=None)
kb.mappings.bind(
    contract_id,
    field_path,
    concept_id,
    contract_version=None,
    state="mapped",
    actor=None,
    confidence=None,
)
kb.mappings.approve(mapping_id, actor, reason=None)
kb.mappings.remap(mapping_id, concept_id, actor, reason=None)
kb.mappings.mark_technical_only(contract_id, field_path, actor=None)
kb.mappings.history(mapping_id)

`health`¶

Purpose:

Run and inspect semantic readiness checks.

Recommended methods:

kb.health.run(target_type, target_id, thresholds=None)
kb.health.get(target_type, target_id, latest=True)
kb.health.issues(target_type=None, target_id=None, severity=None)
kb.health.assert_passes(target_type, target_id, min_coverage=None)

assert_passes should be optimized for CI and raise a structured error when checks fail.

`governance`¶

Purpose:

Manage proposals, reviews, approval policy, and merge gates.

Recommended methods:

kb.governance.create_proposal(title, change_set, actor, workspace=None)
kb.governance.validate_proposal(proposal_id)
kb.governance.review(proposal_id, reviewer, decision, comment=None)
kb.governance.merge(proposal_id, actor)
kb.governance.impact(change_set)

`context`¶

Purpose:

Serve approved semantic context to humans, services, and agents.

Recommended methods:

kb.context.build(
    concept_id=None,
    contract_id=None,
    field_path=None,
    query=None,
    workspace=None,
    purpose=None,
    token_budget=2000,
    actor=None,
)
kb.context.get(context_pack_id)
kb.context.explain(evidence_id)

Return model:

ContextPack(
    id: str,
    target: dict,
    approximate_tokens: int,
    entries: list[ContextEntry],
    evidence: EvidenceEnvelope,
    content_hash: str,
)

Remote Python Client¶

For remote consumers, provide the same method shape over HTTP:

from pycharter.semantic.client import SemanticWorkbenchClient

kb = SemanticWorkbenchClient(
    base_url="https://pycharter.example.com",
    token="...",
)

report = kb.health.run("workspace", "finance")

This avoids forcing users to choose between "local API" and "remote API" mental models.

API Design Rules¶

Return typed models, not raw dictionaries, for the public Python facade.
Include actor, workspace, source_uri, and evidence where relevant.
Use stable IDs for all durable objects.
Make mutating calls idempotent where possible.
Provide both list and detail methods for every major object.
Use the same state vocabulary across Python, HTTP, and UI.
Keep advanced RDF/SHACL/reasoning APIs available, but not required for the golden path.

HTTP API Proposal¶

The HTTP API should be resource-oriented, versioned, and aligned to the same service boundaries as the Python facade.

Recommended base path:

/api/v1/semantic

Workspaces¶

Purpose:

Manage semantic domains/schemes as user-facing workspaces.

Endpoints:

GET    /api/v1/semantic/workspaces
POST   /api/v1/semantic/workspaces
GET    /api/v1/semantic/workspaces/{workspace_id}
PATCH  /api/v1/semantic/workspaces/{workspace_id}
GET    /api/v1/semantic/workspaces/{workspace_id}/summary

Notes:

If workspaces are implemented as concept-scheme aliases, the API should still expose the simpler workspace vocabulary.

Assets¶

Purpose:

Browse imported source assets.

Endpoints:

GET    /api/v1/semantic/assets
GET    /api/v1/semantic/assets/{asset_id}
POST   /api/v1/semantic/assets/{asset_id}/refresh
DELETE /api/v1/semantic/assets/{asset_id}

Recommended query parameters:

workspace_id
source_type
contract_id
status
q
page
page_size

Imports¶

Purpose:

Run and inspect import/ingest jobs.

Endpoints:

GET    /api/v1/semantic/imports
POST   /api/v1/semantic/imports
GET    /api/v1/semantic/imports/{import_id}
GET    /api/v1/semantic/imports/{import_id}/assets
GET    /api/v1/semantic/imports/{import_id}/suggestions
POST   /api/v1/semantic/imports/{import_id}/rerun

Request body for POST /imports:

{
  "workspace_id": "finance",
  "source": {
    "kind": "upload",
    "uri": "file://orders.sql"
  },
  "options": {
    "adapter": "sql",
    "recursive": true,
    "generate_suggestions": true,
    "use_cache": true
  },
  "actor": "alice"
}

For multipart upload, use:

POST /api/v1/semantic/imports:upload

Suggestions¶

Purpose:

Review generated suggestions.

Endpoints:

GET    /api/v1/semantic/suggestions
GET    /api/v1/semantic/suggestions/{suggestion_id}
POST   /api/v1/semantic/suggestions/{suggestion_id}/accept
POST   /api/v1/semantic/suggestions/{suggestion_id}/dismiss
POST   /api/v1/semantic/suggestions/{suggestion_id}/request-changes
POST   /api/v1/semantic/suggestions:batch-accept
POST   /api/v1/semantic/suggestions:batch-dismiss

Recommended query parameters:

workspace_id
status
suggestion_type
confidence
source_asset_id
origin
reviewer
page
page_size

Concepts¶

Purpose:

Manage business concepts and relationships.

Endpoints:

GET    /api/v1/semantic/concepts
POST   /api/v1/semantic/concepts
GET    /api/v1/semantic/concepts/{concept_id}
PATCH  /api/v1/semantic/concepts/{concept_id}
DELETE /api/v1/semantic/concepts/{concept_id}
GET    /api/v1/semantic/concepts/{concept_id}/relationships
POST   /api/v1/semantic/concepts/{concept_id}/relationships
GET    /api/v1/semantic/concepts/{concept_id}/where-used
GET    /api/v1/semantic/concepts/{concept_id}/lineage
GET    /api/v1/semantic/concepts/{concept_id}/inferred-relationships

Recommended query parameters for GET /concepts:

workspace_id
q
concept_type
tier
status
owner
page
page_size

Mappings¶

Purpose:

Manage field-to-concept bindings.

Endpoints:

GET    /api/v1/semantic/mappings
POST   /api/v1/semantic/mappings
GET    /api/v1/semantic/mappings/{mapping_id}
PATCH  /api/v1/semantic/mappings/{mapping_id}
POST   /api/v1/semantic/mappings/{mapping_id}/approve
POST   /api/v1/semantic/mappings/{mapping_id}/remap
POST   /api/v1/semantic/mappings/{mapping_id}/mark-technical-only
GET    /api/v1/semantic/mappings/{mapping_id}/history
POST   /api/v1/semantic/contracts/{contract_id}/mappings:suggest
GET    /api/v1/semantic/contracts/{contract_id}/mappings

Recommended query parameters:

workspace_id
contract_id
contract_version
field_path
concept_id
state
page
page_size

Health¶

Purpose:

Run and inspect semantic readiness checks.

Endpoints:

POST   /api/v1/semantic/health/runs
GET    /api/v1/semantic/health/runs/{run_id}
GET    /api/v1/semantic/health/latest
GET    /api/v1/semantic/health/issues
POST   /api/v1/semantic/health/assert

Request body for POST /health/runs:

{
  "target": {
    "type": "workspace",
    "id": "finance"
  },
  "thresholds": {
    "min_coverage_pct": 80,
    "fail_on_deprecated_concepts": true
  }
}

Governance¶

Purpose:

Manage proposals, reviews, impact previews, and merge gates.

Endpoints:

GET    /api/v1/semantic/proposals
POST   /api/v1/semantic/proposals
GET    /api/v1/semantic/proposals/{proposal_id}
PATCH  /api/v1/semantic/proposals/{proposal_id}
POST   /api/v1/semantic/proposals/{proposal_id}/validate
POST   /api/v1/semantic/proposals/{proposal_id}/reviews
GET    /api/v1/semantic/proposals/{proposal_id}/reviews
GET    /api/v1/semantic/proposals/{proposal_id}/approval-status
GET    /api/v1/semantic/proposals/{proposal_id}/impact
POST   /api/v1/semantic/proposals/{proposal_id}/merge

Context¶

Purpose:

Serve governed semantic context and evidence.

Endpoints:

POST   /api/v1/semantic/context-packs
GET    /api/v1/semantic/context-packs/{context_pack_id}
POST   /api/v1/semantic/context-packs:preview
GET    /api/v1/semantic/evidence/{evidence_id}
POST   /api/v1/semantic/explain

Request body for POST /context-packs:

{
  "target": {
    "type": "concept",
    "id": "finance:NetRevenue"
  },
  "purpose": "agent_context",
  "actor": "agent:finance-analyst",
  "token_budget": 2000,
  "include": {
    "lineage": true,
    "governance": true,
    "field_mappings": true,
    "inferred_relationships": false
  }
}

Schema and Metadata¶

Purpose:

Expose controlled vocabularies that power UI selectors and validators.

Endpoints:

GET /api/v1/semantic/schema/concept-types
GET /api/v1/semantic/schema/relationship-types
GET /api/v1/semantic/schema/tiers
GET /api/v1/semantic/namespaces
POST /api/v1/semantic/namespaces

Compatibility and Migration¶

Existing endpoints should not be removed abruptly. The recommended migration path is:

Keep existing routes working.
Add the consolidated routes.
Update UI to use consolidated routes.
Mark older routes as compatibility routes in docs.
Add deprecation headers once replacements are stable.

Compatibility examples:

Existing /api/v1/semantic/schemes can remain as the lower-level concept-scheme API.
Existing /api/v1/semantic/search/* can remain but should be wrapped by /concepts?q=... and /mappings?....
Existing /api/v1/semantic/kb/ingest-* can remain but should be wrapped by /imports.

Response Envelope¶

All consolidated HTTP responses should use a predictable envelope for list/detail/action responses.

List response:

{
  "items": [],
  "meta": {
    "page": 1,
    "page_size": 50,
    "total": 0
  }
}

Action response:

{
  "status": "accepted",
  "id": "...",
  "events": [],
  "evidence": {}
}

Error response:

{
  "error": {
    "code": "semantic_mapping_invalid",
    "message": "Field path is not present in the contract schema.",
    "details": {
      "contract_id": "finance/orders",
      "field_path": "orders.net_revenue"
    },
    "fix_hint": "Select a field from the contract schema or refresh the mapping projection."
  }
}

Data Model Recommendations¶

1. Make KB Management Durable¶

The current KB version/link/lineage service should move from in-memory storage to database-backed persistence.

Recommended tables:

semantic_kb_versions
semantic_kb_links
semantic_lineage_records

Acceptance criteria:

Data survives server restart.
API behavior remains compatible.
Tests cover create/list/get/compare/link/trace flows.

2. Add Semantic Assets and Ingest Runs¶

Recommended tables:

semantic_assets
semantic_ingest_runs
semantic_ingest_run_assets

Acceptance criteria:

Every suggestion can be traced to a source asset and ingest run.
Re-running the same source can detect unchanged fingerprints.
Failed/skipped files are visible in UI.

3. Strengthen Suggestion Evidence¶

Enhance the existing suggestion model with a structured evidence field.

Recommended evidence shape:

{
  "source_asset_id": "...",
  "source_uri": "...",
  "extractor": "markdown",
  "source_span": {
    "start": 120,
    "end": 240
  },
  "signals": [
    {
      "kind": "name_match",
      "score": 0.82,
      "explanation": "Field name matched existing concept"
    }
  ],
  "duplicates": [
    {
      "concept_id": "...",
      "score": 0.91
    }
  ]
}

Acceptance criteria:

Review UI can explain every suggestion.
Batch review can sort/filter by evidence strength.
Dismissal reasons are persisted.

4. Make Field Bindings First-Class¶

Field bindings should not be only embedded in contract YAML or scattered across helper tables.

Recommended behavior:

Canonical contract representation still owns field bindings.
Database projection stores searchable/indexable mapping rows.
Saving a contract updates the projection.
Updating mappings in UI writes back to contract representation or creates a reviewed mapping overlay.

Acceptance criteria:

Search by concept returns all bound fields.
Contract health can compute coverage without parsing every contract file every time.
Mapping history is visible.

5. Store Health Snapshots¶

Health checks should be repeatable and trendable.

Acceptance criteria:

Users can compare semantic health across time.
CI can fail on thresholds.
UI can show issue trends.

6. Context Packs Need Stable IDs¶

Context packs should be reproducible artifacts.

Acceptance criteria:

Context pack response includes context_pack_id and content hash.
It includes contract and concept versions.
PyGubernator or another agent runtime can record exactly which context was used.

Implementation Strategy¶

Recommended Sequencing¶

Do not start by building a large new UI shell. Start by consolidating backend workflow state and making one path coherent. Then put a guided UI on top.

Recommended order:

Durable backend workflow state.
Route consolidation and API models.
Import and suggestion evidence.
Review and mapping workflows.
Health/gates.
Context serving.
UX polish and onboarding.

Reuse Existing Components¶

Build on:

pycharter.semantic.kb.ingest
extraction adapters
suggestion queue
concept graph service
semantic health
governance validation
context pack builder
unified editor

Avoid:

Creating another standalone KB UI.
Creating a second suggestion/review queue.
Creating a parallel concept registry.
Making users edit raw ontology YAML for normal workflows.

Backlog by Phase¶

Phase 0: Product Alignment and Workflow Contract¶

Goal:

Define the workflow contract so backend, UI, docs, and tests all target the same journey.

Tasks:

ID	Task	Owner	Priority
P0-001	Write a one-page product spec for the golden path: Import -> Suggest -> Review -> Bind -> Measure -> Serve.	Product/Eng	High
P0-002	Decide whether "domain workspace" is a new model or a UI label over concept schemes.	Eng	High
P0-003	Audit existing routes and classify each as active, deprecated, or internal.	Eng	High
P0-004	Confirm the unified editor is the only forward path for KB/ontology UI.	Product/UX	High
P0-005	Define vocabulary for UI labels: business term, concept, field mapping, semantic health, review.	UX	Medium
P0-006	Define end-to-end demo scenario using one realistic domain.	Product/DevRel	High
P0-007	Create workflow acceptance criteria and baseline user test script.	QA/UX	Medium

Definition of done:

The team agrees on the main workflow.
Deprecated UI/API surfaces are documented.
A sample domain is selected for implementation and testing.

Phase 1: Durable Backend Foundation¶

Goal:

Make workflow state durable and queryable.

Tasks:

ID	Task	Owner	Priority
P1-001	Add DB-backed repository for KB versions, KB links, and lineage records.	Backend	High
P1-002	Add migrations for semantic assets and ingest runs.	Backend	High
P1-003	Add `semantic_assets` model with source URI, type, fingerprint, scheme/domain, and status.	Backend	High
P1-004	Add `semantic_ingest_runs` model with actor, config, counts, errors, and timestamps.	Backend	High
P1-005	Link suggestions to source asset and ingest run IDs.	Backend	High
P1-006	Add repository methods for listing assets by scheme, contract, and source type.	Backend	Medium
P1-007	Add durable mapping projection for field-to-concept bindings if not already sufficiently represented.	Backend	High
P1-008	Add lifecycle events for mapping state transitions.	Backend	Medium
P1-009	Add tests for persistence across service restart/session recreation.	QA	High

Definition of done:

Imported asset, ingest run, suggestion, mapping, and lineage state are durable.
A suggestion can be traced to an ingest run and source asset.
Existing suggestion APIs remain compatible.

Phase 2: Import and Suggestion Generation¶

Goal:

Make it easy to import assets and generate understandable suggestions.

Tasks:

ID	Task	Owner	Priority
P2-001	Design/import wizard API around source type, target scheme, policy, and extraction options.	Backend/UX	High
P2-002	Create unified import route that wraps existing text/upload/extraction paths.	Backend	High
P2-003	Persist skipped files, extraction failures, and warnings.	Backend	High
P2-004	Add structured suggestion evidence model.	Backend	High
P2-005	Add duplicate candidate detection to suggestion generation.	Backend	Medium
P2-006	Add confidence bands: high, medium, low, needs-review.	Backend	Medium
P2-007	Add UI import wizard in unified editor.	Frontend	High
P2-008	Add ingest summary screen with links to suggestion inbox.	Frontend	High
P2-009	Add tests for ingest -> suggestions with source evidence.	QA	High

Definition of done:

A user can import files from the UI and immediately see generated suggestions.
Every suggestion explains its source and confidence.
Failed files do not disappear silently.

Phase 3: Review Inbox and Mapping Workbench¶

Goal:

Make human review fast, clear, and trustworthy.

Tasks:

ID	Task	Owner	Priority
P3-001	Redesign suggestions inbox around source, confidence, type, tier, and reviewer filters.	UX/Frontend	High
P3-002	Add suggestion detail panel with evidence, duplicate candidates, and impact preview.	Frontend	High
P3-003	Add batch accept/dismiss/request-changes workflows.	Backend/Frontend	High
P3-004	Add review decision events with actor, decision, comment, and timestamp.	Backend	High
P3-005	Define direct-accept rules for free-tier suggestions.	Backend/Product	Medium
P3-006	Route domain/core suggestions into proposal/review workflow when required.	Backend	High
P3-007	Build mapping workbench: contract fields, concepts, suggested mappings, and coverage.	Frontend	High
P3-008	Add mapping actions: accept, remap, mark technical-only, add annotation.	Frontend/Backend	High
P3-009	Add mapping lifecycle event display.	Frontend	Medium
P3-010	Add tests for suggestion review -> concept/materialization -> mapping update.	QA	High

Definition of done:

A reviewer can process suggestions without leaving the workflow.
Approved suggestions materialize into the correct registry.
A user can bind fields to approved concepts from the UI.

Phase 4: Semantic Health and Governance Gates¶

Goal:

Turn semantic completeness and governance into measurable, actionable checks.

Tasks:

ID	Task	Owner	Priority
P4-001	Expand semantic health service with domain, contract, concept, and field scopes.	Backend	High
P4-002	Store semantic health snapshots.	Backend	Medium
P4-003	Add actionable issue model with fix links.	Backend/Frontend	High
P4-004	Add coverage thresholds by domain/contract/tier.	Backend	Medium
P4-005	Integrate SHACL governance validation into health/gate results.	Backend	Medium
P4-006	Add proposal gate checks for impacted concepts, fields, contracts, and deprecated usage.	Backend	High
P4-007	Add health dashboard in unified editor.	Frontend	High
P4-008	Add CI/API endpoint for semantic health gate.	Backend	Medium
P4-009	Add tests for health checks and proposal gates.	QA	High

Definition of done:

Users can see what is blocking semantic readiness.
Health issues link to where they can be fixed.
CI can run semantic checks against contracts/domains.

Phase 5: Governed Context and Agent Readiness¶

Goal:

Serve approved semantic context to users, APIs, and agents.

Tasks:

ID	Task	Owner	Priority
P5-001	Add stable `context_pack_id` and content hash to context pack responses.	Backend	High
P5-002	Include contract version, concept version, source URI, and policy status in context packs.	Backend	High
P5-003	Define and implement minimal evidence envelope model.	Backend	High
P5-004	Add context preview UI for concepts, contracts, and fields.	Frontend	Medium
P5-005	Add API for retrieving context by concept, field, contract, or query.	Backend	High
P5-006	Add policy-aware context filtering.	Backend	Medium
P5-007	Add optional MCP server/tool surface for agent consumers.	Backend/Integrations	Medium
P5-008	Add PyGubernator integration tests if used as primary agent runtime.	Integrations/QA	Medium

Definition of done:

Agents and APIs can request governed semantic context.
Every context response includes enough evidence for audit.
Context can be traced back to approved concepts, mappings, and sources.

Phase 6: Production Hardening and Adoption¶

Goal:

Make the workflow reliable, scalable, documented, and easy to adopt.

Tasks:

ID	Task	Owner	Priority
P6-001	Add role/permission checks across import, review, mapping, and governance actions.	Backend	High
P6-002	Add pagination and filtering to all high-volume routes.	Backend	High
P6-003	Add background job support for large imports.	Backend	Medium
P6-004	Add audit export for governance decisions and mappings.	Backend	Medium
P6-005	Add sample domain with contracts, docs, DDL, suggestions, and expected outputs.	DevRel	High
P6-006	Write user guide for the end-to-end workflow.	Docs	High
P6-007	Write admin guide for governance policy and permissions.	Docs	Medium
P6-008	Add Playwright coverage for core workflow.	QA	High
P6-009	Add migration guide for existing ontology users.	Docs/Eng	Medium

Definition of done:

The workflow is usable by a new user following docs.
Large imports and review queues remain responsive.
Governance/audit requirements are covered.

Multi-Agent Implementation Orchestration Plan¶

The implementation should be managed as a traceable program, not as a series of disconnected patches. If multiple AI agents are used, one agent should act as the orchestrator and own the kanban board, task decomposition, dependencies, and integration reviews.

Recommended Claude entry point:

Use /orchestrate from pycharter/.claude/skills/orchestrate/SKILL.md to run this proposal through the kanban board with explicit owners, write scopes, review gates, QA evidence, and phase summaries.

Recommended Agent Roles¶

1. Orchestrator Agent¶

Responsibilities:

Maintain the kanban board.
Split work into small tasks.
Assign ownership and write boundaries.
Track dependencies and blockers.
Review cross-agent conflicts.
Decide when work is ready for integration.
Keep the implementation aligned to this proposal.

2. Backend Agent¶

Responsibilities:

Data models.
Migrations.
Repositories.
API routes.
Service-layer logic.
Backend tests.

3. Frontend Agent¶

Responsibilities:

Unified editor UI changes.
Semantic home.
Import flow.
Suggestions inbox.
Mapping workbench.
Health panel.
Context preview.
Frontend tests.

4. QA Agent¶

Responsibilities:

Test planning.
Regression coverage.
API contract tests.
UI workflow tests.
Browser verification checklist.
Accessibility and layout checks.

5. Docs/DevRel Agent¶

Responsibilities:

User workflow docs.
API docs.
Migration notes.
Sample domain walkthrough.
Release notes.

6. Reviewer/Integrator Agent¶

Responsibilities:

Review completed patches.
Check consistency with architecture.
Resolve small integration issues.
Confirm test evidence.
Prepare final merge summary.

Kanban Board Format¶

Create and maintain a markdown kanban board at:

pycharter/docs/guides/kb-ontology-workflow-kanban.md

Recommended columns:

Backlog
Ready
In Progress
Review
QA
Blocked
Done

Each card should use this shape:

### P2-004: Add structured suggestion evidence model

- Phase: Phase 2
- Area: Backend
- Owner: Backend Agent
- Status: In Progress
- Priority: High
- Risk: Medium
- Source: `kb-ontology-workflow-proposal.md` -> Phase 2
- Dependencies: P1-002, P1-005
- Write scope:
  - `src/pycharter/db/models/semantic/*`
  - `src/pycharter/api/models/semantic_suggestions.py`
  - `tests/...`
- Acceptance criteria:
  - Suggestions persist structured evidence.
  - Existing suggestion APIs remain compatible.
  - Tests cover list/detail/accept flows with evidence.
- Test evidence:
  - Pending
- Review notes:
  - Pending

Traceability Requirements¶

Every implementation task should include:

Task ID from this proposal.
Owner.
Status.
Files touched.
Acceptance criteria.
Test evidence.
Review notes.
Links or references to related tasks.
Any architectural decision made while implementing.

Every completed task should end with a short implementation note:

Completion note:
- Changed files:
- Behavior added:
- Tests run:
- Residual risks:
- Follow-up tasks:

Quality Gates¶

No task should move to Done unless:

Acceptance criteria are satisfied.
Relevant tests pass.
Lint/type checks pass where applicable.
UI changes have screenshot or browser verification notes.
Public APIs have request/response examples or tests.
Docs are updated when user-facing behavior changes.
The orchestrator or reviewer confirms the change does not violate the surgical UI/UX constraints.

Recommended Prompt for AI Multi-Agent Orchestration¶

Use the following prompt with an AI system capable of orchestrating multiple coding agents. Replace bracketed values as needed.

You are the implementation orchestrator for PyCharter's practical knowledge-base and ontology workflow.

Repository context:
- Repo root: [REPO_ROOT]
- Main proposal: pycharter/docs/guides/kb-ontology-workflow-proposal.md
- UI architecture references:
  - pycharter/docs/guides/editor-architecture-adr.md
  - pycharter/docs/guides/editor-workspace-unification-handoff.md
  - pycharter/docs/guides/editor-verification-checklist.md

Mission:
Implement the workflow described in the proposal in a careful, traceable, phased way:
Import assets -> suggest concepts -> review -> approve -> bind fields -> measure semantic health -> serve governed context.

Non-negotiable constraints:
1. Keep changes surgical.
2. Do not build a new standalone knowledge-base app.
3. Use the existing unified editor, workspace store, editor shell, semantic components, and existing design patterns.
4. Do not introduce a new visual design language.
5. Preserve compatibility with existing semantic endpoints until replacements are stable.
6. Do not let agents work on overlapping write scopes at the same time.
7. Every task must have acceptance criteria and test evidence.
8. Every user-facing change must update docs or examples.
9. Every UI change must include browser/screenshot verification notes.
10. All implementation must be traceable through a kanban board.

Initial orchestration tasks:
1. Read the main proposal and editor architecture references.
2. Create or update:
   pycharter/docs/guides/kb-ontology-workflow-kanban.md
3. Convert the proposal backlog into kanban cards.
4. Start with Phase 0 and Phase 1 only unless explicitly approved to proceed further.
5. Assign non-overlapping work to specialized agents:
   - Backend Agent
   - Frontend Agent
   - QA Agent
   - Docs Agent
   - Reviewer/Integrator Agent

Kanban columns:
- Backlog
- Ready
- In Progress
- Review
- QA
- Blocked
- Done

Card format:
Each card must include:
- Task ID
- Phase
- Area
- Owner
- Status
- Priority
- Risk
- Source proposal section
- Dependencies
- Write scope
- Acceptance criteria
- Test evidence
- Review notes

Agent operating procedure:
1. Orchestrator selects a small batch of Ready tasks.
2. Orchestrator assigns each task to one agent with a clear write scope.
3. Worker agents inspect relevant files before editing.
4. Worker agents implement only their assigned scope.
5. Worker agents update the kanban card with changed files, tests, and residual risks.
6. Reviewer/Integrator reviews each completed task before it moves to QA.
7. QA Agent runs or specifies tests and browser checks.
8. Orchestrator moves cards only after evidence is recorded.
9. Blockers must be written into the Blocked column with owner and unblock condition.
10. At the end of each phase, produce a phase review summary.

Phase 0 target:
- Confirm unified editor is the primary UI path.
- Audit current semantic/ontology routes and screens.
- Decide which routes/screens are active, deprecated, or internal.
- Create shared UI vocabulary and status labels.
- Create the initial kanban board.

Phase 1 target:
- Make KB management durable.
- Add semantic assets and ingest runs.
- Link suggestions to source assets and ingest runs.
- Add tests for durable persistence and traceability.

Review checklist for every patch:
- Does it align with the proposal?
- Is the write scope respected?
- Does it avoid broad refactors?
- Does it preserve existing behavior?
- Are tests included or explicitly justified?
- Are user-facing changes documented?
- Are UI changes consistent with the existing editor UI?
- Are migration/compatibility risks recorded?

Quality gate commands:
Before declaring a task done, run the smallest relevant test set first.
Then run broader checks when touching shared code.
Record exact commands and outcomes in the kanban card.

Expected outputs:
1. Updated kanban board.
2. Implementation patches.
3. Test evidence.
4. Review notes.
5. Phase summary.
6. Updated documentation.

Start by creating the kanban board and proposing the first 5-8 Ready cards from Phase 0 and Phase 1. Do not implement until the board and task ownership are clear.

Suggested First Kanban Cards¶

Use these as the starting board seed.

ID	Title	Area	Priority	Initial Owner
KAN-001	Create kanban board and convert proposal backlog into cards	Process	High	Orchestrator
UX0-001	Audit current semantic/ontology screens and classify keep/merge/deprecate/internal	Frontend/UX	High	Frontend Agent
UX0-002	Document existing UI patterns to reuse for semantic workflow	Frontend/UX	High	Frontend Agent
P0-003	Audit existing semantic routes and classify active/deprecated/internal	Backend	High	Backend Agent
P0-005	Define shared user-facing vocabulary and status labels	UX/Docs	Medium	Docs Agent
P1-001	Add DB-backed repository for KB versions, links, and lineage	Backend	High	Backend Agent
P1-002	Add migrations for semantic assets and ingest runs	Backend	High	Backend Agent
QA0-001	Define workflow verification checklist and test matrix	QA	High	QA Agent

Suggested First 30 Days¶

The highest-leverage first month should focus on coherence, not breadth.

Recommended first sprint:

Create durable asset and ingest run models.
Link suggestions to source evidence.
Build a minimal import summary UI.
Build a better suggestion detail panel.
Add one sample domain that exercises the whole flow.

Recommended second sprint:

Add mapping workbench MVP.
Add semantic health issue list.
Add batch review.
Add mapping lifecycle events.
Write the end-to-end user guide.

By the end of 30 days, the target demo should be:

Import a sample contract, DDL file, and Markdown glossary.
Generate suggestions.
Review and accept concepts.
Bind contract fields.
See coverage improve.
Open context preview for an approved concept.

Acceptance Criteria for the Overall Workflow¶

The workflow should be considered successful when:

A new user can complete the sample journey in under 20 minutes.
A data steward can understand why each suggestion was made.
A data engineer can map contract fields without editing YAML manually.
A domain owner can approve or reject changes without learning RDF/SHACL.
A failed semantic health check provides a clear fix path.
Every approved mapping has source, actor, time, and review history.
A context pack can be traced back to approved concepts and source assets.
The UI and API expose the same workflow states.
Restarting the server does not lose KB versions, links, lineage, ingest runs, or review decisions.
The deprecated standalone knowledge-base page is no longer part of the primary navigation or documentation path.

Metrics to Track¶

Product metrics:

Time to first approved concept.
Time to first approved field binding.
Percentage of imported fields mapped.
Suggestions accepted vs dismissed.
Suggestions requiring manual changes.
Review queue age.
Semantic health score over time.

Quality metrics:

Duplicate concept rate.
Invalid mapping rate.
Deprecated concept usage.
Broken relationship count.
Context pack missing-evidence rate.

Operational metrics:

Import duration.
Extraction failure rate.
Suggestion generation duration.
Health check duration.
Review action latency.

Risks and Mitigations¶

Risk	Impact	Mitigation
Too much ontology terminology overwhelms users.	Adoption drops.	Use workflow labels first; expose formal terms in details.
Duplicate concepts proliferate.	Trust drops.	Add duplicate detection and merge suggestions early.
Suggestions lack explanation.	Reviewers do not trust automation.	Require structured evidence for every suggestion.
In-memory KB management remains in production path.	Data loss and unreliability.	Move KB management to DB-backed repositories in Phase 1.
UI diverges from backend governance rules.	Incorrect approvals.	UI should render backend-provided policy/gate status.
Mapping write-back becomes ambiguous.	Contract drift.	Define canonical source of truth and projection rules before UI work.
Agent-facing context exposes unapproved data.	Governance failure.	Context APIs must filter by approval/policy state.

Open Decisions¶

Should "domain workspace" become a persisted model, or should concept schemes remain the only domain boundary?
Should field mappings write directly back into contract artifacts, or should PyCharter maintain a reviewed mapping overlay that can later export back to contracts?
Which user roles are required for the first release?
Which source type should be the first-class sample: DDL, contract YAML, Markdown glossary, dbt manifest, or a combination?
Should MCP support be built directly into PyCharter, or exposed through PyGubernator integration first?
What is the minimum evidence envelope required before agent-facing context is considered safe?

Recommended Positioning¶

The feature should not be positioned as "an ontology editor" first. That is accurate but too narrow and too abstract.

Recommended positioning:

PyCharter's semantic workbench helps teams turn contracts, schemas, and domain knowledge into approved business concepts, governed field mappings, semantic health checks, and agent-ready context.

Shorter version:

Governed business meaning for data contracts and agents.

Summary¶

PyCharter's knowledge base and ontology layer can become a highly valuable part of the platform if it is organized around a single practical workflow. The backend already has many of the necessary primitives. The next step is to make the system feel like one coherent product:

Import assets, review suggestions, bind concepts to data, measure semantic health, and serve trusted context.

The backlog above prioritizes durable workflow state, explainable suggestions, mapping usability, semantic health, and agent-ready context. Those are the changes most likely to make the layer intuitive, useful, and adoptable by real users.

Proposal: Practical Knowledge Base and Ontology Workflow¶

Executive Summary¶

Product Thesis¶

Current Assessment¶

What Exists Today¶

Main Gaps¶

Target Users¶

Data Steward¶

Data Engineer¶

Domain Owner¶

Analyst or Agent Developer¶

Platform Admin¶

Design Principles¶

1. One Primary Workflow¶

2. Progressive Disclosure¶

3. Evidence Beside Every Suggestion¶

4. Reversible and Auditable Actions¶

5. Status-Driven Navigation¶

6. UI and API Should Mirror Each Other¶

7. Agent Readiness Comes From Human Governance¶

Proposed User Workflow¶

Step 1: Create or Select a Domain Workspace¶

Step 2: Import Assets¶

Step 3: Normalize Inventory¶

Step 4: Generate Suggestions¶

Step 5: Review and Approve¶

Step 6: Bind Concepts to Contract Fields¶

Step 7: Measure Semantic Health¶

Step 8: Serve Governed Context¶

Proposed Information Architecture¶

Primary UI Areas¶

1. Semantic Home¶

2. Import Wizard¶

3. Suggestions Inbox¶

4. Concept Workbench¶

5. Mapping Workbench¶

6. Semantic Health¶

7. Context Preview¶

Surgical UI/UX Enhancement Plan¶

UI/UX Principles¶

1. Preserve the Existing Editor Mental Model¶

2. Rename Concepts in the UI Before Rebuilding Screens¶

3. Make Status Visible Everywhere¶

4. Use Existing Component Families¶

5. Make Review Actions Fast¶

6. Do Not Over-Decorate¶

UI/UX User Journey: Revenue Agent Readiness¶

Journey Overview¶

Screen-by-Screen Experience¶

1. Semantic Home: "What needs attention?"¶

2. Import Entry Point: "Bring in what we already have"¶

3. Suggestions Inbox: "Review meaning with evidence"¶

4. Mapping Workbench: "Bind terms to real fields"¶

5. Domain Approval: "Approve sensitive definitions"¶

6. Semantic Health: "What still blocks readiness?"¶

7. Agent Context Preview: "What exactly will the AI see?"¶

8. Published Outcome: "Agent-ready governed meaning"¶

Why This Journey Shows Tremendous Value¶

Proposed UI Changes by Surface¶

A. Editor Landing / Semantic Home¶

B. Import Entry Point¶

C. Suggestions Inbox¶

D. Mapping Workbench¶

E. Semantic Health Panel¶

F. Concept Detail / Workbench¶

G. Context Preview¶

UI/UX Implementation Phases¶

UX Phase 0: Inventory and Guardrails¶

UX Phase 1: Semantic Home and Import Entry¶

UX Phase 2: Review Inbox¶

UX Phase 3: Mapping Workbench¶

UX Phase 4: Health and Context Preview¶

UI/UX QA Checklist¶

Backend Architecture¶

Core Registries¶

Asset Registry¶

Ingest Run Registry¶

Concept Registry¶

Mapping Registry¶

Suggestion Registry¶

`workspaces`¶

`assets`¶

`imports`¶

`suggestions`¶

`concepts`¶

`mappings`¶

`health`¶

`governance`¶

`context`¶