If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/madebybowtie/FlagKit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 10 active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live madebybowtie/FlagKit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/madebybowtie/FlagKit.

What it runs against: a local clone of madebybowtie/FlagKit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in madebybowtie/FlagKit | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 781 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of madebybowtie/FlagKit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/madebybowtie/FlagKit.git
#   cd FlagKit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of madebybowtie/FlagKit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "madebybowtie/FlagKit(\\.git)?\\b" \\
  && ok "origin remote is madebybowtie/FlagKit" \\
  || miss "origin remote is not madebybowtie/FlagKit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 781 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~751d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/madebybowtie/FlagKit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

FlagKit is a comprehensive multi-format flag icon library for Apple platforms (iOS, macOS, tvOS) and the web, providing 250+ country and region flags as PNG (1x/2x/3x) and SVG assets. It wraps these assets in a Swift framework with a programmatic API to retrieve flags by country code and apply styling (circle, rounded, square shapes), solving the problem of sourcing and managing high-quality localized flag imagery. Asset-driven architecture: Assets/PNG/ contains flag PNGs organized by ISO 3166-1 alpha-2 country code (AD.png, AE.png, etc.) with 1x/2x/3x variants; Assets/FlagKit.xcassets is the bundled Asset Catalog for direct Xcode integration; Swift wrapper code provides a Flag(countryCode:) initializer and .image(style:) method for styling; a demo project in Sources/Swift/FlagKitDemo-iOS shows usage patterns.

iOS/macOS/tvOS developers building locale-aware apps that need to display country flags (e.g., in language pickers, user profiles, location selectors) without manually sourcing and maintaining flag assets across multiple resolutions.

Production-ready. The project shows active maintenance with Travis CI integration, multi-package manager support (CocoaPods, Carthage, SwiftPM), and a clean Asset Catalog structure (Assets/FlagKit.xcassets). The codebase is lean (~21KB Swift, ~1KB Objective-C) with clear documentation and a demo project, suggesting stability and deliberate design.

Low risk. The library has minimal dependencies (asset-driven, no external SDKs) and a single-source-of-truth PNG/SVG repository. Main risk is that flag sovereignty is politically sensitive—definitions of which entities get flags may face community disagreements. No version constraints or breaking API patterns are evident, but commit recency and issue backlog are not visible from the data provided.

No commit recency or open PR data is visible in the provided snapshot, so current development status is unclear. The presence of a sample project and multi-package manager support suggests maintenance was recent, but specific ongoing work is not evident.

git clone https://github.com/madebybowtie/FlagKit.git
cd FlagKit
# For CocoaPods: pod install
# For Carthage: carthage update --platform iOS
# For SwiftPM: add as package dependency in Xcode

Daily commands: No dev server or CLI build step. This is a framework library: integrate via CocoaPods (pod install), Carthage (carthage update), SwiftPM, or manual copy of Assets/FlagKit.xcassets. Launch the included iOS demo project in Sources/Swift/FlagKitDemo-iOS via open FlagKitDemo-iOS.xcodeproj && cmd+R in Xcode.

• Assets/FlagKit.xcassets: The core Xcode Asset Catalog bundled in the framework; all 250+ flag images are registered here for runtime loading via UIImage(named:in:compatibleWith:).
• Assets/PNG/: Source directory containing all 1x/2x/3x PNG flag assets organized by ISO 3166-1 alpha-2 country code; any flag addition or update starts here.
• Assets/Flags.md: Public reference list of all 250+ flags provided by the library; maps country codes to human-readable names for documentation and discoverability.
• Sources/Swift/FlagKitDemo-iOS: Sample iOS app demonstrating the Flag API, styling options, and best practices for real-world integration.
• .travis.yml: CI configuration ensuring builds pass on each commit; validates framework compilation across supported platforms.

Adding a new flag: Drop PNG files at Assets/PNG/{CountryCode}.png, {CountryCode}@2x.png, {CountryCode}@3x.png (using ISO 3166-1 alpha-2 codes). Updating styling: Modify Swift enum in the framework source (likely in Sources/Swift/—exact file not listed). Testing: Add test cases in demo project or unit tests if present. Documentation: Update Assets/Flags.md with new country entries.

No hidden environment variables or complex setup detected from the file list. Potential gotchas: (1) Asset Catalog bundle may need explicit framework target membership in Xcode; (2) Flag country codes must be exact ISO 3166-1 alpha-2 (e.g., 'US' not 'USA'); (3) Styling APIs may not be available on macOS (per README note); (4) Manual asset copy (vs. framework) requires keeping PNG variants in sync with @2x/@3x naming.

• ISO 3166-1 alpha-2 country codes — FlagKit's entire asset naming scheme (AD, AE, AF, etc.) is keyed on ISO 3166-1 alpha-2; learning this standard is mandatory for adding flags or debugging mismatches.
• Xcode Asset Catalogs (xcassets) — FlagKit bundles all 250+ flags in Assets/FlagKit.xcassets, which enables automatic 1x/2x/3x resolution selection at runtime; understanding Asset Catalogs is critical for maintaining the framework.
• Image resolution scaling (@2x, @3x) — FlagKit provides flags in three resolutions (1x for iPad 2/old devices, @2x for iPhone, @3x for iPhone 6+) to balance file size and clarity; crucial when adding new assets.
• Framework bundling and Asset Catalog distribution — FlagKit uses a dynamic framework to bundle the Asset Catalog, allowing single-command installation via CocoaPods/Carthage; understanding how frameworks encapsulate and distribute assets is key to modifying packaging.
• Locale and regionCode API — The README example uses Locale.current.regionCode to fetch the user's country; this is how FlagKit integrates with iOS i18n for automatic locale-specific flag display.

• lipis/flag-icons — Alternative comprehensive flag icon library (330+ flags in SVG/CSS), popular in web projects; overlaps same use case but broader platform support.
• joielechong/countryicons — Another flag icon set for Android and web; direct competitor for cross-platform mobile app developers.
• apple/swift-system — Official Apple Swift system library; relevant for developers using FlagKit who want native Swift APIs for locale and region code access.
• apple/swift-package-manager — FlagKit supports SwiftPM distribution; understanding SPM packaging is essential for maintaining and versioning this framework.
• onmyway133/Locale — Lightweight Swift library for working with Locale and region codes; commonly paired with FlagKit to map user locales to flag country codes.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add SVG format support documentation and asset catalog export

The README mentions 'SVG files' are provided but there's no Assets/SVG directory visible in the file structure. The repo should either document where SVG assets are stored, add them to the asset catalog, or create a guide for converting/exporting PNG assets to SVG. This is critical for web usage mentioned in the description.

• [ ] Verify if Assets/SVG directory exists or needs to be created with SVG versions of all flags
• [ ] Update Assets/Flags.md to document SVG availability and location
• [ ] If SVGs don't exist, add a build script or documentation on the vector source files used to generate them
• [ ] Update README.md Installation section to clarify SVG usage for web projects

Create automated test suite to validate flag asset completeness

With 250+ flag PNG files across 3 resolutions (@1x, @2x, @3x), there's no visible test infrastructure to ensure all country codes have complete file sets. A test should verify no missing variants and validate image dimensions/formats.

• [ ] Create a test file (e.g., Tests/FlagKitTests.swift or tests/assets.test.js) that iterates Assets/PNG directory
• [ ] Verify each country code has exactly 3 files (base, @2x, @3x) with correct dimensions
• [ ] Add test to .travis.yml CI pipeline to run on every commit
• [ ] Document expected dimensions in Assets/Flags.md if not already present

Add Linux/web distribution support via GitHub Actions and NPM package

The repo only shows Travis CI and Apple platform support (SwiftPM, Carthage, CocoaPods). For a 'web' usage project, there's no npm package or cross-platform CI. Adding GitHub Actions workflow and npm registry support would broaden accessibility.

• [ ] Create .github/workflows/release.yml to automate PNG/SVG asset publishing on version tags
• [ ] Add package.json for npm distribution of PNG/SVG files
• [ ] Update .travis.yml or replace with GitHub Actions for multi-platform testing
• [ ] Update README.md with npm installation instructions: 'npm install flagkit'

• Add unit tests for the Flag(countryCode:) initializer to verify nil-safety and coverage of all 250+ country codes against Assets/Flags.md (currently no test files visible).
• Create a web demo or static HTML page that displays all flags from Assets/PNG/ as an interactive gallery, allowing filtering by region—useful for discoverability beyond the iOS demo.
• Document macOS styling limitations (noted in README) with concrete code examples showing which .image(style:) calls fail on macOS and recommended workarounds.

FlagKit is a static asset repository for flag icons with minimal security risk. The codebase contains no executable code, dependencies, or dynamic functionality that could introduce common vulnerabilities. The primary concerns are related to supply chain management and CI/CD configuration rather than code-level issues.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.