feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command

Add /ultraresearch-local for structured research combining local codebase
analysis with external knowledge via parallel agent swarms. Produces research
briefs with triangulation, confidence ratings, and source quality assessment.

New command: /ultraresearch-local with modes --quick, --local, --external, --fg.
New agents: research-orchestrator (opus), docs-researcher, community-researcher,
security-researcher, contrarian-researcher, gemini-bridge (all sonnet).
New template: research-brief-template.md.

Integration: --research flag in /ultraplan-local accepts pre-built research
briefs (up to 3), enriches the interview and exploration phases. Planning
orchestrator cross-references brief findings during synthesis.

Design principle: Context Engineering — right information to right agent at
right time. Research briefs are structured artifacts in the pipeline:
ultraresearch → brief → ultraplan --research → plan → ultraexecute.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

skills/ms-ai-engineering/references/rag-architecture/graphrag-knowledge-graphs.md

@@ -0,0 +1,303 @@
+# GraphRAG - Knowledge Graphs and Relationship Extraction
+
+**Last updated:** 2026-02
+**Status:** Preview
+**Category:** RAG Architecture & Semantic Search
+
+---
+
+## Introduksjon
+
+GraphRAG representerer en fundamental utvidelse av tradisjonell Retrieval-Augmented Generation (RAG) ved å innføre knowledge graphs som strukturert grunnlag for kontekstrikere søk og resonnering. Der klassisk RAG baserer seg på vector similarity for å finne relevante dokumentchunks, utnytter GraphRAG eksplisitte entitets- og relasjonsforbindelser for å svare på spørsmål som krever forståelse av hierarkier, avhengigheter og komplekse sammenhenger.
+
+GraphRAG kombinerer tre komplementære retrieval-strategier: tradisjonell database-RAG for fakta-lookup, vector search for semantisk likhet, og graph traversal for relasjonelle spørsmål. Dette hybridsystemet, ofte kalt **OmniRAG**, velger dynamisk den mest hensiktsmessige søkemetoden basert på brukerens spørsmålstype. For eksempel vil spørsmål om "hvem rapporterer til hvem" utløse graph traversal, mens "finn lignende dokumenter" bruker vector search.
+
+I Microsoft-økosystemet implementeres GraphRAG primært via **CosmosAIGraph** — en løsning som utnytter Azure Cosmos DB sine skalerbare capabilities for både dokument-, vektor- og graph-databaser. Ved å kombinere disse i én plattform, muliggjør CosmosAIGraph sofistikerte datamodeller for use cases som anbefalingssystemer, supply chain-analyse, fraud detection og organisasjonshierarkier.
+
+---
+
+## Kjernekomponenter
+
+GraphRAG-systemet består av flere integrerte lag som sammen muliggjør relasjonell søking og resonnering:
+
+| Komponent | Beskrivelse | Microsoft-teknologi |
+|-----------|-------------|---------------------|
+| **Entity Extraction** | Identifiserer og trekker ut navngitte entiteter (personer, organisasjoner, lokasjoner) fra tekst | Azure AI Language Service (NER v3), GenAI Prompt skill |
+| **Relationship Graphs** | Representerer entiteter som nodes og relasjoner som edges i en graph-struktur | Azure Cosmos DB (graph API), Kusto Query Language (KQL) graph semantics |
+| **Graph Indexing** | Lagrer og indekserer graph-strukturen for effektiv traversal og søk | Azure Cosmos DB indexing, Azure AI Search (hybrid indexing) |
+| **Traversal Queries** | Søkemekanismer for å navigere graph-strukturen (pattern matching, shortest path, neighborhood search) | KQL `graph-match`, `graph-shortest-paths`, Labeled Property Graphs (LPG) |
+| **Entity Linking** | Forbinder ekstraherte entiteter med eksisterende knowledge bases (f.eks. Wikipedia) for normalisering og anrikning | Azure AI Language Entity Linking skill |
+| **Vector Integration** | Kombinerer graph traversal med vector embeddings for hybrid retrieval | Azure AI Search (hybrid queries), Azure OpenAI Embedding skill |
+
+### Entity Extraction og Enrichment
+
+Entity extraction-prosessen transformerer ustrukturert tekst til strukturerte entitets-objekter med metadata:
+
+- **Built-in skills**: Entity Recognition (v3) fra Azure AI Search extraherer 14 kategorier (Person, Organization, Location, Quantity, DateTime, URL, Email)
+- **Custom extraction**: GenAI Prompt skill tillater few-shot learning for domene-spesifikke entiteter
+- **Entity normalization**: Wikipedia IDs, Bing IDs og confidence scores legges til for datakvalitet
+
+### Graph Database Modeller
+
+Microsoft Fabric og Azure støtter **Labeled Property Graphs (LPG)** som standard graph-modell:
+
+- **Nodes (entiteter)**: Har labels (typer), properties (attributter) og unique IDs
+- **Edges (relasjoner)**: Har types (f.eks. "knows", "depends_on"), properties (weights, timestamps) og retning
+- **Schema flexibility**: Kan utvikles inkrementelt uten rigid schema constraints
+- **RDF ikke støttet**: Resource Description Framework (RDF) er ikke støttet i Microsoft Fabric per 2026
+
+---
+
+## Arkitekturmønstre
+
+### 1. Local vs. Global GraphRAG
+
+| Mønster | Beskrivelse | Bruksområde | Fordeler | Ulemper |
+|---------|-------------|-------------|----------|---------|
+| **Local GraphRAG** | Traverserer graph fra query-relevante nodes (1-3 hops) | Q&A om spesifikke entiteter ("Hvem jobbet sammen med Person A?") | Rask, presis, lav compute-kostnad | Mister global kontekst, begrensede inferenser |
+| **Global GraphRAG** | Bygger community-struktur og summaries over hele graph | Strategiske spørsmål ("Hvilke temaer dominerer dette dokumentsettet?") | Holistisk forståelse, oppdager skjulte mønstre | Compute-intensiv, høy latency, krever pre-processing |
+
+**Best practice**: Bruk local GraphRAG for runtime queries, global GraphRAG for batch-analyse og insight-generering.
+
+### 2. Hybrid Vector + Graph Retrieval
+
+Kombinerer vector similarity search med graph traversal for maksimal kontekst-relevans:
+
+```
+1. Vector search → finn top-N semantisk relevante chunks
+2. Entity extraction → identifiser entiteter i chunks
+3. Graph traversal → ekspander med relaterte entiteter (1-2 hops)
+4. Re-ranking → kombiner vector scores og graph proximity
+5. Context assembly → samle anriket kontekst for LLM-prompt
+```
+
+**Fordeler**: Balanserer semantic similarity med autoritative relasjoner, reduserer hallucinations.
+**Ulemper**: Høyere latency, krever orchestration-logikk (f.eks. Microsoft Agent Framework).
+
+### 3. Entity-Centric Retrieval
+
+Spesielt effektivt for domener med mange-til-mange relasjoner (supply chains, org charts, knowledge bases):
+
+- **Pattern**: Query → entity lookup → relationship expansion → document retrieval
+- **Eksempel**: "Finn alle avhengigheter for produkt X" → hent product node → travers "depends_on" edges → returner relaterte produkter
+- **Microsoft-implementasjon**: CosmosAIGraph med OmniRAG dynamic routing
+
+---
+
+## Beslutningsveiledning
+
+### Når bruke GraphRAG?
+
+| Scenario | Anbefaling | Alternativ |
+|----------|------------|-----------|
+| Spørsmål om relasjoner, hierarkier, avhengigheter | ✅ **GraphRAG** (graph traversal) | Vector RAG (vil feile på relasjonelle inferenser) |
+| Spørsmål om "hvem", "hva", "hvor" (fakta) | Database RAG | GraphRAG (overkill) |
+| Semantisk likhetssøk ("finn lignende") | Vector RAG | GraphRAG (unødvendig kompleksitet) |
+| Ukjent query-type (varierende brukerformål) | **OmniRAG** (dynamisk routing) | Single-mode RAG (suboptimalt) |
+| Eksplorative spørsmål ("vis sammenhenger") | Global GraphRAG | Local/vector RAG (for snevert) |
+
+### Vanlige feil
+
+| Feil | Konsekvens | Løsning |
+|------|------------|---------|
+| Bruker GraphRAG for alle queries | Unødvendig høy latency og kostnad | Implementer OmniRAG-routing basert på query classification |
+| Ingen entity normalization | Duplikate nodes ("Microsoft" vs. "Microsoft Corp") | Bruk Entity Linking skill + canonical ID-mapping |
+| For dype traversals (5+ hops) | Eksplosjonsartet resultatmengde, timeout | Begrens til 1-3 hops, bruk shortest-path algorithms |
+| Ignorerer vector component i hybrid mode | Mister semantisk kontekst | Alltid kombiner graph + vector for best recall |
+| Mangelfull graph indexing | Treg traversal-performance | Bruk Azure Cosmos DB indexing policies, pre-compute communities |
+
+### Røde flagg
+
+- 🚩 **Persondata i graph nodes**: GDPR-risiko hvis PII lagres uten anonymisering
+- 🚩 **Ingen confidence thresholds**: Lav-kvalitet entity extraction forurenser graph
+- 🚩 **Statisk graph model**: Manglende evne til å håndtere nye entitetstyper
+- 🚩 **Single graph instance**: Ingen fallback hvis graph queries feiler
+
+---
+
+## Integrasjon med Microsoft-stakken
+
+### Azure Cosmos DB for GraphRAG
+
+**CosmosAIGraph** ([aka.ms/cosmosaigraph](https://aka.ms/cosmosaigraph)) er Microsofts native GraphRAG-løsning:
+
+- **Multi-model database**: Document, vector og graph i samme container
+- **OmniRAG-orchestration**: Automatisk routing basert på query intent
+- **Skalering**: Global distribution, RU-based throughput (handles massive graphs)
+- **API**: Gremlin API (graph traversal), SQL API (document queries)
+
+### Azure AI Search
+
+- **Hybrid indexing**: Lagrer både vectors og graph-metadata (entity IDs, relationship types)
+- **Enrichment pipeline**: Entity Recognition skill + custom skills for graph-population
+- **Reranking**: Semantic ranking kombinert med graph proximity scores
+- **Knowledge base API**: Preview-feature for agentic retrieval (includes graph-aware context assembly)
+
+### Azure OpenAI
+
+- **Embedding models**: `text-embedding-3-large` for vector component av hybrid GraphRAG
+- **Prompt engineering**: GenAI Prompt skill for few-shot entity extraction
+- **Reasoning over graphs**: GPT-4 og Opus for complex graph reasoning (path explanations, multi-hop inferenser)
+
+### Microsoft Agent Framework
+
+- **Orchestration**: Koordinerer database → graph → vector → LLM pipelines
+- **Agent tools**: Graph query tools (Gremlin, KQL) som agent capabilities
+- **Streaming**: Inkrementell graph traversal for low-latency agent responses
+
+### Kusto Query Language (KQL) Graph Semantics
+
+Microsoft Fabric og Azure Data Explorer støtter KQL graph operators:
+
+- **`make-graph`**: Konstruerer graph fra tabular data (node/edge tables)
+- **`graph-match`**: Pattern matching (f.eks. "MATCH (Person)-[:knows]->(Friend)")
+- **`graph-shortest-paths`**: Finn korteste sti mellom nodes
+- **`graph-to-table`**: Konverter graph-resultater til tabeller for videre analyse
+
+---
+
+## Offentlig sektor (Norge)
+
+### GDPR og knowledge graphs
+
+GraphRAG introduserer spesifikke personvernrisiki i offentlig sektor:
+
+| Risiko | GDPR-artikkel | Tiltak |
+|--------|---------------|--------|
+| **PII i entity nodes** | Art. 5 (data minimization) | Anonymiser personnavn, bruk pseudonymiserte IDs |
+| **Relasjonsgraphs som profilering** | Art. 22 (automated decisions) | Eksplisitt consent for graph-baserte anbefalinger |
+| **Persistent graph storage** | Art. 17 (right to erasure) | Implementer node/edge deletion workflows |
+| **Cross-border graph traversal** | Art. 44 (international transfers) | Bruk Azure Norway regions, regional graph partitions |
+
+### Compliance-krav
+
+- **Schrems II**: GraphRAG-data i Azure Norway (oslo-region) oppfyller EU data residency
+- **Arkivloven**: Graph snapshots må inkluderes i dokumentasjonssystemer (OEP-format krever flattening)
+- **Sikkerhetsloven**: Graph-relasjoner klassifiseres som "indirekte identifikatorer" (kryptér edges med sensitive relasjoner)
+
+### Anbefalt pattern for offentlig sektor
+
+```
+1. Dokument-ingest → entity extraction (anonymisert) → graph population
+2. PII-nodes lagres i separate encrypted containers (ikke i graph)
+3. Graph-relasjoner bruker role-based IDs ("Leder-1234" vs. "Navn Navnesen")
+4. Query-logging for auditability (hvem traverserte hvilke relasjoner?)
+5. Automatic retention policies (delete old graph data per arkivplan)
+```
+
+---
+
+## Kostnad og lisensiering
+
+### Azure Cosmos DB Pricing (GraphRAG-spesifikt)
+
+| Komponent | Enhet | Pris (NOK, ca.) | Optimalisering |
+|-----------|-------|-----------------|----------------|
+| **Graph storage** | 1 GB/måned | ~12 NOK | Partition graphs per domain, archive old communities |
+| **Read/write RUs** | 100 RU/s provisioned | ~500 NOK/måned | Use serverless for sporadic queries, autoscaling for variable load |
+| **Graph traversal** | Per query complexity (RUs) | Variabel (5-100 RU per traversal) | Cache frequent paths, limit hop depth |
+| **Global distribution** | Per region replica | +100% storage cost | Use single-region for dev/test |
+
+**TCO-eksempel** (medium-sized graph):
+- 100 GB graph data
+- 10,000 queries/dag (mix av local/global)
+- Provisioned 1000 RU/s
+- **Månedlig kostnad**: ~8,000 NOK
+
+### Azure AI Search for Hybrid GraphRAG
+
+- **Indexing**: Entity extraction via built-in skills (~2-5 NOK per 1000 documents)
+- **Hybrid queries**: Vector + metadata filtering (inkludert i query cost, ingen ekstra)
+- **Semantic ranking**: +100 NOK/måned (1000 queries/month tier)
+
+### Optimaliseringstips
+
+1. **Pre-compute global graph summaries** (kjør batch jobs nattetid, cache results)
+2. **Partition graphs by tenant/department** (reduser traversal scope, isoler cost per user)
+3. **Use materialized views** (lagre frequently-queried subgraphs som denormalized tables)
+4. **Tiered retrieval**: Start med cheap vector search, eskalér til graph kun hvis nødvendig
+5. **Monitor RU consumption**: Set alerts på >80% RU usage, auto-scale eller optimize queries
+
+---
+
+## For arkitekten (Cosmo)
+
+### Spørsmål å stille kunden
+
+1. **Hvilke typer spørsmål skal systemet besvare?**
+   → Avgjør om local, global eller hybrid GraphRAG trengs
+
+2. **Finnes det etablerte ontologies/taxonomier i domenet?**
+   → Kan gjenbruke eksisterende entity types vs. bygge fra scratch
+
+3. **Hvor mange entiteter og relasjoner forventes?**
+   → Dimensjonerer Cosmos DB RUs, vurderer partitioning-strategi
+
+4. **Hvor dynamisk er dataen? (Hvor ofte endres relasjoner?)**
+   → Statiske graphs kan pre-kompileres, dynamiske krever real-time indexing
+
+5. **Finnes det persondata i entitetene?**
+   → GDPR-vurdering, pseudonymisering, consent-flows
+
+6. **Hva er latency-kravene for queries?**
+   → <500ms: bruk pre-computed paths; <2s: local traversal; >2s: global ok
+
+7. **Skal brukere kunne visualisere graphen?**
+   → Krever frontend integration (f.eks. vis.js, D3.js) + export API
+
+8. **Hvilke downstream-systemer skal konsumere graph-innsikter?**
+   → API design, batch export vs. streaming updates
+
+### Fallgruver
+
+| Fallgruve | Hvorfor det skjer | Hvordan unngå |
+|-----------|-------------------|---------------|
+| **Graph blir for stor til å travers** | Ukontrollert vekst (ingen arkivering) | Implementer retention policies, partition per time period |
+| **Entity extraction av lav kvalitet** | Default NER-modeller ikke trent på domene | Fine-tune custom models, bruk GenAI Prompt skill med examples |
+| **Ingen fail-over fra graph til vector** | Hard dependency på graph availability | Implementer OmniRAG-fallback: graph timeout → vector search |
+| **Query performance degrades over tid** | Index fragmentation, ingen maintenance | Schedule index rebuilds, monitor query latencies |
+| **Brukere forventer real-time graph updates** | Batch-basert indexing pipeline | Set forventninger (eventual consistency), eller bruk streaming ingestion |
+
+### Anbefalinger per modenhetsnivå
+
+| Nivå | Startpunkt | Neste steg |
+|------|------------|-----------|
+| **Eksplorerende** (ingen RAG i prod) | Pilot med CosmosAIGraph demo dataset | Evaluer query patterns, beslut local vs. global |
+| **Etablert RAG** (vector search i prod) | Legg til entity extraction i existing pipeline | A/B-test hybrid vs. vector-only retrieval |
+| **Modenhet** (multi-modal RAG) | Implementer OmniRAG routing | Optimize cost med query classification + tiered retrieval |
+| **Avansert** (custom graph reasoning) | Tren fine-tuned entity linker på domene-data | Build custom graph reasoning agents (multi-hop, counterfactual queries) |
+
+---
+
+## Kilder og verifisering
+
+### Microsoft Learn-kilder (fra MCP-research)
+
+| Seksjon | URL | Konfidensnivå |
+|---------|-----|---------------|
+| CosmosAIGraph arkitektur | https://learn.microsoft.com/en-us/azure/cosmos-db/gen-ai/cosmos-ai-graph | ✅ Verified (2026-02) |
+| Graph semantics i KQL | https://learn.microsoft.com/en-us/kusto/query/graph-semantics-overview | ✅ Verified (2026-02) |
+| Entity Recognition skill (v3) | https://learn.microsoft.com/en-us/azure/search/cognitive-search-skill-entity-recognition-v3 | ✅ Verified (2026-02) |
+| Azure AI Search transparency note | https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/search/transparency-note | ✅ Verified (2026-02) |
+| RAG solution design guide | https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/rag/rag-solution-design-and-evaluation-guide | ✅ Verified (2026-02) |
+| Labeled Property Graphs (LPG) | https://learn.microsoft.com/en-us/fabric/graph/graph-data-models | ✅ Verified (2026-02) |
+
+### Konfidens per seksjon
+
+- **Introduksjon**: ✅ Verified (direkte fra Cosmos DB docs)
+- **Kjernekomponenter**: ✅ Verified (Azure AI Search + Cosmos DB capabilities)
+- **Arkitekturmønstre**: ⚠️ Baseline (inferert fra best practices, ikke eksplisitt dokumentert)
+- **Beslutningsveiledning**: ⚠️ Baseline (syntetisert fra multiple sources)
+- **Microsoft-integrasjon**: ✅ Verified (official API docs)
+- **Offentlig sektor**: ⚠️ Baseline (GDPR-prinsipper applisert på GraphRAG-kontekst)
+- **Kostnad**: ⚠️ Baseline (Cosmos DB pricing, estimater fra modell-kunnskap)
+
+### Notater
+
+- CosmosAIGraph er en GitHub-basert løsning (preview), ikke en fullt integrert Azure-tjeneste per februar 2026
+- Global GraphRAG-konseptet er inspirert av research (ikke eksplisitt Microsoft-terminologi)
+- NOK-priser er omregnet fra USD med kurs 10.5 (verifiser mot aktuelle priser)
+
+---
+
+**For Cosmo Skyberg:** Dette dokumentet skal brukes for å vurdere om GraphRAG-patterns er hensiktsmessige for kundens use case. Prioriter alltid spørsmålet: "Trenger vi faktisk graph traversal, eller holder vector search?" — kompleksitet skal forsvares med klare fordeler. Ved tvil, start med hybrid approach (vector + metadata) før full graph commitment.