@wictorwilen/cocogen 1.0.0

package/dist/init/templates/dotnet/Program.cs.ejs

@@ -0,0 +1,487 @@
+using Azure.Identity;
+using Azure.Core;
+using Microsoft.Graph;
+using Microsoft.Graph.Models.ExternalConnectors;
+using Microsoft.Graph.Models.ODataErrors;
+using Microsoft.Kiota.Abstractions;
+using Microsoft.Kiota.Abstractions.Serialization;
+using System.Net.Http.Headers;
+using System.Text;
+using System.Text.Json;
+
+using <%= namespaceName %>.Datasource;
+using <%= namespaceName %>.Generated;
+
+var command = args.Length > 0 ? args[0] : "";
+
+static string RequiredEnv(string name)
+{
+    var value = Environment.GetEnvironmentVariable(name);
+    if (string.IsNullOrWhiteSpace(value))
+        throw new InvalidOperationException($"Missing env var: {name}");
+    return value;
+}
+
+static GraphServiceClient CreateGraphClient()
+{
+    var credential = CreateCredential();
+
+    var graph = new GraphServiceClient(credential, new[] { "https://graph.microsoft.com/.default" });
+    graph.RequestAdapter.BaseUrl = SchemaConstants.GraphBaseUrl;
+    return graph;
+}
+
+static ClientSecretCredential CreateCredential()
+{
+    var tenantId = RequiredEnv("TENANT_ID");
+    var clientId = RequiredEnv("CLIENT_ID");
+    var clientSecret = RequiredEnv("CLIENT_SECRET");
+    return new ClientSecretCredential(tenantId, clientId, clientSecret);
+}
+
+static async Task<string> GetAccessTokenAsync(ClientSecretCredential credential)
+{
+    var token = await credential.GetTokenAsync(
+        new TokenRequestContext(new[] { "https://graph.microsoft.com/.default" })
+    );
+    return token.Token;
+}
+
+static async Task<HttpResponseMessage> GraphRequestAsync(ClientSecretCredential credential, HttpMethod method, string url, object? body = null)
+{
+    using var http = new HttpClient();
+    var token = await GetAccessTokenAsync(credential);
+    http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
+
+    var request = new HttpRequestMessage(method, url);
+    if (body is not null)
+    {
+        var json = JsonSerializer.Serialize(body);
+        request.Content = new StringContent(json, Encoding.UTF8, "application/json");
+    }
+
+    return await http.SendAsync(request);
+}
+
+static bool IsStatus(ApiException ex, int statusCode)
+{
+    return ex.ResponseStatusCode is int sc && sc == statusCode;
+}
+
+static async Task EnsureConnectionAsync(GraphServiceClient graph, string connectionId)
+{
+    var name = RequiredEnv("CONNECTION_NAME");
+    var description = RequiredEnv("CONNECTION_DESCRIPTION");
+
+    try
+    {
+        await graph.External.Connections[connectionId].GetAsync();
+        return;
+    }
+    using Azure.Core;
+    using Azure.Identity;
+    using Microsoft.Extensions.Configuration;
+    using Microsoft.Graph;
+    using Microsoft.Graph.Models.ExternalConnectors;
+    using Microsoft.Graph.Models.ODataErrors;
+    using Microsoft.Kiota.Abstractions;
+    using Microsoft.Kiota.Abstractions.Serialization;
+    using System.CommandLine;
+    using System.Net.Http.Headers;
+    using System.Text;
+    using System.Text.Json;
+
+    using <%= namespaceName %>.Datasource;
+    using <%= namespaceName %>.Schema;
+
+    var configuration = new ConfigurationBuilder()
+        .SetBasePath(Directory.GetCurrentDirectory())
+        .AddJsonFile("appsettings.json", optional: true)
+        .AddJsonFile("appsettings.Development.json", optional: true)
+        .AddEnvironmentVariables()
+        .Build();
+
+    string RequiredSetting(string key)
+    {
+        var value = configuration[key];
+        if (string.IsNullOrWhiteSpace(value))
+            throw new InvalidOperationException($"Missing configuration: {key}");
+        return value;
+    }
+
+    string ConnectionId() => RequiredSetting("Connection:Id");
+    string ConnectionName() => RequiredSetting("Connection:Name");
+    string ConnectionDescription() => RequiredSetting("Connection:Description");
+
+    ClientSecretCredential CreateCredential()
+    {
+        var tenantId = RequiredSetting("AzureAd:TenantId");
+        var clientId = RequiredSetting("AzureAd:ClientId");
+        var clientSecret = RequiredSetting("AzureAd:ClientSecret");
+        return new ClientSecretCredential(tenantId, clientId, clientSecret);
+    }
+
+    GraphServiceClient CreateGraphClient()
+    {
+        var credential = CreateCredential();
+        var graph = new GraphServiceClient(credential, new[] { "https://graph.microsoft.com/.default" });
+        graph.RequestAdapter.BaseUrl = SchemaConstants.GraphBaseUrl;
+        return graph;
+    }
+
+    async Task<string> GetAccessTokenAsync(ClientSecretCredential credential)
+    {
+        var token = await credential.GetTokenAsync(
+            new TokenRequestContext(new[] { "https://graph.microsoft.com/.default" })
+        );
+        return token.Token;
+    }
+
+    async Task<HttpResponseMessage> GraphRequestAsync(ClientSecretCredential credential, HttpMethod method, string url, object? body = null)
+    {
+        using var http = new HttpClient();
+        var token = await GetAccessTokenAsync(credential);
+        http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
+
+        var request = new HttpRequestMessage(method, url);
+        if (body is not null)
+        {
+            var json = JsonSerializer.Serialize(body);
+            request.Content = new StringContent(json, Encoding.UTF8, "application/json");
+        }
+
+        return await http.SendAsync(request);
+    }
+
+    bool IsStatus(ApiException ex, int statusCode)
+    {
+        return ex.ResponseStatusCode is int sc && sc == statusCode;
+    }
+
+    async Task EnsureConnectionAsync(GraphServiceClient graph, string connectionId)
+    {
+        try
+        {
+            await graph.External.Connections[connectionId].GetAsync();
+            return;
+        }
+        catch (ApiException ex) when (IsStatus(ex, 404))
+        {
+            // Create below.
+        }
+
+        var connection = new ExternalConnection
+        {
+            Id = connectionId,
+            Name = ConnectionName(),
+            Description = ConnectionDescription(),
+        };
+
+        if (!string.IsNullOrWhiteSpace(SchemaConstants.ContentCategory))
+        {
+            // contentCategory is currently only exposed on the /beta endpoint.
+            connection.AdditionalData ??= new Dictionary<string, object>();
+            connection.AdditionalData["contentCategory"] = SchemaConstants.ContentCategory!;
+        }
+
+        await graph.External.Connections.PostAsync(connection);
+    }
+
+    async Task PatchSchemaAsync(GraphServiceClient graph, string connectionId)
+    {
+        var schema = SchemaPayload.BuildSchema();
+        await graph.External.Connections[connectionId].Schema.PatchAsync(schema);
+    }
+
+    async Task ProvisionAsync()
+    {
+        var graph = CreateGraphClient();
+        var connectionId = ConnectionId();
+
+        await EnsureConnectionAsync(graph, connectionId);
+        await PatchSchemaAsync(graph, connectionId);
+    <% if (isPeopleConnector) { -%>
+        await RegisterProfileSourceAsync(connectionId);
+    <% } -%>
+
+        Console.WriteLine("ok: provisioned");
+    }
+
+    async Task PutItemAsync(GraphServiceClient graph, string connectionId, Item item)
+    {
+        var itemId = ItemPayload.GetItemId(item);
+
+        var externalItem = ItemPayload.ToExternalItem(item);
+
+        // NOTE: The external connectors surface may not expose a typed PutAsync on all SDK versions.
+        // We still use the Graph SDK's request adapter and models for a strongly-typed payload.
+        var requestInfo = new RequestInformation
+        {
+            HttpMethod = Method.PUT,
+            UrlTemplate = "{+baseurl}/external/connections/{connectionId}/items/{itemId}",
+            PathParameters = new Dictionary<string, object>
+            {
+                { "baseurl", graph.RequestAdapter.BaseUrl },
+                { "connectionId", connectionId },
+                { "itemId", itemId },
+            },
+        };
+
+        requestInfo.Headers.Add("Accept", "application/json");
+        requestInfo.SetContentFromParsable(graph.RequestAdapter, "application/json", externalItem);
+
+        var errorMapping = new Dictionary<string, ParsableFactory<IParsable>>
+        {
+            { "4XX", ODataError.CreateFromDiscriminatorValue },
+            { "5XX", ODataError.CreateFromDiscriminatorValue },
+        };
+
+        await graph.RequestAdapter.SendAsync<ExternalItem>(
+            requestInfo,
+            ExternalItem.CreateFromDiscriminatorValue,
+            errorMapping
+        );
+    }
+
+    async Task IngestAsync(string? csvPath)
+    {
+        var graph = CreateGraphClient();
+        var connectionId = ConnectionId();
+
+        var configuredCsv = configuration["Csv:Path"] ?? "data.csv";
+        var path = string.IsNullOrWhiteSpace(csvPath) ? configuredCsv : csvPath;
+
+        IItemSource source = new CsvItemSource(path);
+
+        var count = 0;
+        await foreach (var item in source.GetItemsAsync())
+        {
+            await PutItemAsync(graph, connectionId, item);
+            count++;
+        }
+
+        Console.WriteLine($"ok: ingested {count} item(s)");
+    }
+
+    <% if (isPeopleConnector) { -%>
+    async Task RegisterProfileSourceAsync(string connectionId)
+    {
+        var credential = CreateCredential();
+        var webUrl = RequiredSetting("ProfileSource:WebUrl");
+        var displayName = configuration["ProfileSource:DisplayName"] ?? ConnectionName();
+        var kind = configuration["ProfileSource:Kind"];
+
+        var payload = new Dictionary<string, object?>
+        {
+            ["sourceId"] = connectionId,
+            ["displayName"] = displayName,
+            ["webUrl"] = webUrl,
+        };
+
+        if (!string.IsNullOrWhiteSpace(kind))
+            payload["kind"] = kind;
+
+        var create = await GraphRequestAsync(
+            credential,
+            HttpMethod.Post,
+            $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources",
+            payload
+        );
+
+        if (!create.IsSuccessStatusCode && create.StatusCode != System.Net.HttpStatusCode.Conflict)
+        {
+            var text = await create.Content.ReadAsStringAsync();
+            throw new InvalidOperationException($"Failed to register profile source (HTTP {(int)create.StatusCode}): {text}");
+        }
+
+        var sourceUrl = $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources(sourceId='{connectionId}')";
+        await UpdateProfileSourcePrecedenceAsync(credential, sourceUrl, prepend: true);
+    }
+
+    async Task UnregisterProfileSourceAsync(string connectionId)
+    {
+        var credential = CreateCredential();
+        var sourceUrl = $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources(sourceId='{connectionId}')";
+
+        await UpdateProfileSourcePrecedenceAsync(credential, sourceUrl, prepend: false);
+
+        var res = await GraphRequestAsync(
+            credential,
+            HttpMethod.Delete,
+            $"{SchemaConstants.GraphBaseUrl}/admin/people/profileSources(sourceId='{connectionId}')"
+        );
+
+        if (!res.IsSuccessStatusCode && res.StatusCode != System.Net.HttpStatusCode.NotFound)
+        {
+            var text = await res.Content.ReadAsStringAsync();
+            throw new InvalidOperationException($"Failed to delete profile source (HTTP {(int)res.StatusCode}): {text}");
+        }
+    }
+
+    async Task UpdateProfileSourcePrecedenceAsync(ClientSecretCredential credential, string sourceUrl, bool prepend)
+    {
+        var res = await GraphRequestAsync(
+            credential,
+            HttpMethod.Get,
+            $"{SchemaConstants.GraphBaseUrl}/admin/people/profilePropertySettings"
+        );
+
+        if (!res.IsSuccessStatusCode)
+        {
+            var text = await res.Content.ReadAsStringAsync();
+            throw new InvalidOperationException($"Failed to list profile property settings (HTTP {(int)res.StatusCode}): {text}");
+        }
+
+        var json = await res.Content.ReadAsStringAsync();
+        using var doc = JsonDocument.Parse(json);
+        if (!doc.RootElement.TryGetProperty("value", out var values) || values.ValueKind != JsonValueKind.Array)
+            return;
+
+        foreach (var entry in values.EnumerateArray())
+        {
+            if (!entry.TryGetProperty("id", out var idProp) || idProp.ValueKind != JsonValueKind.String)
+                continue;
+
+            var id = idProp.GetString() ?? string.Empty;
+            if (string.IsNullOrWhiteSpace(id)) continue;
+
+            List<string> existing = new();
+            if (entry.TryGetProperty("prioritizedSourceUrls", out var urls) && urls.ValueKind == JsonValueKind.Array)
+            {
+                foreach (var url in urls.EnumerateArray())
+                {
+                    if (url.ValueKind == JsonValueKind.String)
+                        existing.Add(url.GetString() ?? "");
+                }
+            }
+
+            existing = existing.Where((u) => !string.IsNullOrWhiteSpace(u) && u != sourceUrl).ToList();
+            var updated = prepend ? new[] { sourceUrl }.Concat(existing).ToList() : existing;
+
+            var patch = new Dictionary<string, object?>
+            {
+                ["@odata.type"] = "#microsoft.graph.profilePropertySetting",
+                ["prioritizedSourceUrls"] = updated,
+            };
+
+            var patchRes = await GraphRequestAsync(
+                credential,
+                HttpMethod.Patch,
+                $"{SchemaConstants.GraphBaseUrl}/admin/people/profilePropertySettings/{id}",
+                patch
+            );
+
+            if (!patchRes.IsSuccessStatusCode)
+            {
+                var text = await patchRes.Content.ReadAsStringAsync();
+                throw new InvalidOperationException($"Failed to update profile property setting {id} (HTTP {(int)patchRes.StatusCode}): {text}");
+            }
+        }
+    }
+    <% } -%>
+
+    async Task DeleteConnectionAsync()
+    {
+        var graph = CreateGraphClient();
+        var connectionId = ConnectionId();
+
+    <% if (isPeopleConnector) { -%>
+        await UnregisterProfileSourceAsync(connectionId);
+    <% } -%>
+
+        try
+        {
+            await graph.External.Connections[connectionId].DeleteAsync();
+        }
+        catch (ApiException ex) when (IsStatus(ex, 404))
+        {
+            // Already deleted.
+        }
+        Console.WriteLine("ok: deleted");
+    }
+
+    var csvOption = new Option<string>("--csv", description: "CSV path");
+
+    var root = new RootCommand("Connector CLI generated by gcgen");
+
+    var provisionCommand = new Command("provision", "Create or update the connection and schema");
+    provisionCommand.SetHandler(async () => await ProvisionAsync());
+
+    var ingestCommand = new Command("ingest", "Ingest items from CSV");
+    ingestCommand.AddOption(csvOption);
+    ingestCommand.SetHandler(async (string? csv) => await IngestAsync(csv), csvOption);
+
+    var deleteCommand = new Command("delete", "Delete the connection");
+    deleteCommand.SetHandler(async () => await DeleteConnectionAsync());
+
+    root.AddCommand(provisionCommand);
+    root.AddCommand(ingestCommand);
+    root.AddCommand(deleteCommand);
+
+    <% if (isPeopleConnector) { -%>
+    var registerCommand = new Command("register-profile-source", "Register the connection as a profile source");
+    registerCommand.SetHandler(async () => await RegisterProfileSourceAsync(ConnectionId()));
+    root.AddCommand(registerCommand);
+    <% } -%>
+
+    return await root.InvokeAsync(args);
+{
+    var graph = CreateGraphClient();
+    var connectionId = RequiredEnv("CONNECTION_ID");
+
+    var csvArg = GetArgValue("--csv", allArgs);
+    var csvPath = !string.IsNullOrWhiteSpace(csvArg)
+        ? csvArg
+        : (Environment.GetEnvironmentVariable("CSV_PATH") ?? "data.csv");
+
+    IItemSource source = new CsvItemSource(csvPath);
+
+    var count = 0;
+    await foreach (var item in source.GetItemsAsync())
+    {
+        await PutItemAsync(graph, connectionId, item);
+        count++;
+    }
+
+    Console.WriteLine($"ok: ingested {count} item(s)");
+}
+
+try
+{
+    if (command == "provision")
+    {
+        await ProvisionAsync();
+    }
+    else if (command == "ingest")
+    {
+        await IngestAsync(args);
+    }
+    else if (command == "register-profile-source")
+    {
+        await RegisterProfileSourceAsync(RequiredEnv("CONNECTION_ID"));
+    }
+    else if (command == "delete")
+    {
+        await DeleteConnectionAsync();
+    }
+    else
+    {
+        Console.WriteLine("Usage:");
+        Console.WriteLine("  dotnet run -- provision");
+        Console.WriteLine("  dotnet run -- ingest --csv path/to.csv");
+        Console.WriteLine("  dotnet run -- register-profile-source");
+        Console.WriteLine("  dotnet run -- delete");
+        Environment.ExitCode = 1;
+    }
+}
+catch (ApiException ex)
+{
+    Console.Error.WriteLine("error: Graph request failed");
+    Console.Error.WriteLine(ex.Message);
+    Environment.ExitCode = 1;
+}
+catch (Exception ex)
+{
+    Console.Error.WriteLine("error: " + ex.Message);
+    Environment.ExitCode = 1;
+}

package/dist/init/templates/dotnet/README.md.ejs

@@ -0,0 +1,56 @@
+Generated by cocogen.
+
+## Quickstart
+1) Edit `appsettings.json` with your tenant/app/connection details.
+2) `dotnet build`
+3) `dotnet run -- provision`
+4) `dotnet run -- ingest --csv ./data.csv`
+5) (Optional) `dotnet run -- delete`
+
+<% if (isPeopleConnector) { -%>
+Note: this is a People connector (preview). It uses Graph beta endpoints and registers the connection as a profile source during `provision`.
+<% } -%>
+
+## Graph API version note
+If your schema sets `@coco.connection({ contentCategory: "..." })`, provisioning must use Microsoft Graph **/beta** because `externalConnection.contentCategory` is currently exposed on the beta endpoint.
+
+## Multiple connections
+This generated CLI currently targets a single connection ID from configuration. Multi-connection support is planned for a future version.
+
+## Requirements
+- .NET 10 SDK
+- Microsoft Entra app registration with application permissions:
+  - `ExternalConnection.ReadWrite.OwnedBy`
+  - `ExternalItem.ReadWrite.OwnedBy`
+<% if (isPeopleConnector) { -%>
+  - `PeopleSettings.ReadWrite.All` (required for profile source registration)
+<% } -%>
+
+## TypeSpec editor support
+This project includes `tspconfig.yaml` and a `package.json` with `@wictorwilen/cocogen` as a dev dependency so VS Code can resolve `using coco;`.
+Run `npm install` in this folder to fetch the TypeSpec library.
+
+## Customizing the project
+- **Schema and fields**: edit `schema.tsp` (copied into this folder) and run `cocogen update --out .` to regenerate `Schema/`.
+- **Ingestion**: replace the datasource in `Datasource/` (CSV is the default) and wire it in `Program.cs`.
+- **People connectors**: customize entity payloads in `Schema/PersonEntityOverrides.cs` (kept on updates).
+- **Property transforms**: edit `Schema/PropertyTransforms.cs` to customize per-field parsing/mapping.
+- **Connection defaults**: `@coco.connection` can set `connectionId` and `connectionDescription` defaults for `appsettings.json`.
+- **Profile source defaults**: `@coco.profileSource` sets defaults for `ProfileSource` settings (people connectors only).
+- **Access control**: edit `Schema/ItemPayload.cs` to change ACL behavior.
+
+## Ingest debugging flags
+Use `dotnet run -- ingest` with:
+- `--dry-run` (build payloads without sending)
+- `--limit <n>` (ingest only N items)
+- `--verbose` (print the exact payload sent to Graph)
+
+Note: `--dry-run` does not require Azure AD or connection settings.
+
+## Switching from CSV to another datasource
+1) Implement `IItemSource` in `Datasource/`.
+2) If your source yields raw records, map them to `Item` using `FromCsvRow`-style logic.
+3) Update `Program.cs` to instantiate your new source instead of `CsvItemSource`.
+
+Tip: keep the `IAsyncEnumerable<Item>` pattern for large datasets.
+

package/dist/init/templates/dotnet/appsettings.json.ejs

@@ -0,0 +1,21 @@
+{
+  "AzureAd": {
+    "TenantId": "",
+    "ClientId": "",
+    "ClientSecret": ""
+  },
+  "Connection": {
+    "Id": "<%= connectionId ?? "my-connection-id" %>",
+    "Name": "<%= itemTypeName %>",
+    "Description": "<%= connectionDescription ?? `${itemTypeName} connector generated by cocogen` %>"
+  },
+  "Csv": {
+    "Path": "data.csv"
+  }<% if (isPeopleConnector) { -%>,
+  "ProfileSource": {
+    "WebUrl": "<%= profileSourceWebUrl ?? "https://example.com/people-data" %>",
+    "DisplayName": "<%= profileSourceDisplayName ?? itemTypeName %>",
+    "Priority": "<%= profileSourcePriority ?? "first" %>"
+  }
+<% } -%>
+}

package/dist/init/templates/dotnet/package.json.ejs

@@ -0,0 +1,7 @@
+{
+  "name": "<%= projectName %>-typespec",
+  "private": true,
+  "devDependencies": {
+    "@wictorwilen/cocogen": "^1.0.0"
+  }
+}

package/dist/init/templates/dotnet/project.csproj.ejs

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LangVersion>latest</LangVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" Version="1.17.1" />
+    <% if (graphApiVersion === "beta") { -%>
+    <PackageReference Include="Microsoft.Graph.Beta" Version="5.129.0-preview" />
+    <% } else { -%>
+    <PackageReference Include="Microsoft.Graph" Version="5.100.0" />
+    <% } -%>
+    <PackageReference Include="CsvHelper" Version="33.1.0" />
+    <PackageReference Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
+    <PackageReference Include="Microsoft.Extensions.Configuration" Version="10.0.2" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="10.0.2" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.2" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="appsettings.json" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+</Project>

package/dist/init/templates/dotnet/tspconfig.yaml.ejs

@@ -0,0 +1,2 @@
+imports:
+  - "@wictorwilen/cocogen"

package/dist/init/templates/ts/.env.example.ejs

@@ -0,0 +1,20 @@
+# Azure AD app credentials
+TENANT_ID=
+CLIENT_ID=
+CLIENT_SECRET=
+
+# Graph external connection
+CONNECTION_ID=<%= connectionId ?? "my-connection-id" %>
+CONNECTION_NAME=<%= itemTypeName %>
+CONNECTION_DESCRIPTION=<%= connectionDescription ?? `${itemTypeName} connector generated by cocogen` %>
+
+<% if (isPeopleConnector) { -%>
+# People connector profile source (required for contentCategory=people)
+PROFILE_SOURCE_WEB_URL=<%= profileSourceWebUrl ?? "https://example.com/people-data" %>
+# Optional overrides
+# PROFILE_SOURCE_DISPLAY_NAME=<%= profileSourceDisplayName ?? itemTypeName %>
+# PROFILE_SOURCE_PRIORITY=<%= profileSourcePriority ?? "first" %>
+<% } -%>
+
+# CSV ingestion
+CSV_PATH=data.csv

package/dist/init/templates/ts/README.md.ejs

@@ -0,0 +1,54 @@
+Generated by cocogen.
+
+## Quickstart
+1) Copy `.env.example` to `.env` and fill in values.
+2) `npm install`
+3) `npm run provision`
+4) `npm run ingest`
+5) (Optional) `npm run delete`
+
+<% if (isPeopleConnector) { -%>
+Note: this is a People connector (preview). It uses Graph beta endpoints and registers the connection as a profile source during `provision`.
+<% } -%>
+
+## Graph API version note
+If your schema sets `@coco.connection({ contentCategory: "..." })`, provisioning must use Microsoft Graph **/beta** because `externalConnection.contentCategory` is currently exposed on the beta endpoint.
+
+## Requirements
+- Microsoft Entra app registration with application permissions:
+	- `ExternalConnection.ReadWrite.OwnedBy`
+	- `ExternalItem.ReadWrite.OwnedBy`
+<% if (isPeopleConnector) { -%>
+	- `PeopleSettings.ReadWrite.All` (required for profile source registration)
+<% } -%>
+
+## TypeSpec editor support
+This project includes `tspconfig.yaml` and a devDependency on `@wictorwilen/cocogen` so VS Code can resolve `using coco;`.
+Run `npm install` to fetch the TypeSpec library.
+
+## Customizing the project
+- **Schema and fields**: edit `schema.tsp` (copied into this folder) and run `cocogen update --out .` to regenerate `src/schema`.
+- **Ingestion**: replace the datasource in `src/datasource` (CSV is the default) and wire it in `src/cli.ts`.
+- **People connectors**: customize entity payloads in `src/schema/personEntityOverrides.ts` (kept on updates).
+- **Property transforms**: edit `src/schema/propertyTransforms.ts` to customize per-field parsing/mapping.
+- **Connection defaults**: `@coco.connection` can set `connectionId` and `connectionDescription` defaults for `.env.example`.
+- **Profile source defaults**: `@coco.profileSource` sets defaults for `PROFILE_SOURCE_*` (people connectors only).
+- **Access control**: edit `src/schema/itemPayload.ts` to change ACL behavior.
+
+## Ingest debugging flags
+Use `npm run ingest --` with:
+- `--dry-run` (build payloads without sending)
+- `--limit <n>` (ingest only N items)
+- `--verbose` (print the exact payload sent to Graph)
+
+Note: `--dry-run` does not require CONNECTION_ID, but you still need it for real ingestion.
+
+## Switching from CSV to another datasource
+1) Implement `ItemSource` in `src/datasource`.
+2) If your source yields raw records, map them to `Item` using `fromCsvRow`-style logic.
+3) Update `src/cli.ts` to instantiate your new source instead of `CsvItemSource`.
+
+Tip: keep the streaming `AsyncIterable<Item>` pattern for large datasets.
+
+## Multiple connections
+This generated CLI currently targets a single connection ID from environment variables. Multi-connection support is planned for a future version.