# Francione Design Group — Full Agent Documentation (llms-full.txt)

> Complete technical and operational reference for LLMs, autonomous agents, and developers interacting with Francione Design Group systems, public API, and web resources.

## 1. Company Identity & Service Domain

- **Company Name**: Francione Design Group
- **Legal Entity**: Francione Design Group LLC
- **Primary Website**: https://www.francionedesigngroup.com
- **Industry**: Luxury Hardscaping, Outdoor Living Construction, and Landscape Design
- **State License**: New Jersey Home Improvement Contractor (NJ HIC #13VH13900000)
- **Primary Geographic Region**: Jersey Shore (Monmouth County and Ocean County, New Jersey)
- **Primary Phone**: +1 (908) 442-6654
- **Primary Email**: francionedesigngroup@gmail.com
- **Physical Service Area Address**: Monmouth County, NJ 07701, US

### Core Capabilities
1. **Custom Hardscaping & Paver Patios**: Multi-tier patios, permeable pavers, bluestone, travertine, porcelain, and natural stone walkways.
2. **Outdoor Kitchens & Living Spaces**: Built-in grills, countertops, refrigeration, pizza ovens, pergolas, and bar seating.
3. **Fire Features & Retaining Walls**: Gas fire pits, wood-burning fireplaces, structural retaining walls, and sitting walls.
4. **Landscape Architecture & Design**: 3D design rendering, coastal plant selection, sodding, irrigation, and architectural LED landscape lighting.

---

## 2. CLI Tool Quickstart

Agents and developers can use our zero-dependency CLI tool directly via `npx`:

```bash
# List all services
npx fdg services

# Get service details
npx fdg services hardscaping-outdoor-living --json

# List service area towns in Monmouth County
npx fdg locations --county "Monmouth County" --json

# Get company credentials and contact information
npx fdg contact --json

# Print full OpenAPI 3.1 specification
npx fdg openapi
```

---

## 3. Public REST API Reference

- **Base URL**: `https://www.francionedesigngroup.com/api/v1`
- **Protocol**: HTTPS / REST JSON (OpenAPI 3.1.0)
- **Authentication**: None required for read endpoints (Public)
- **Headers**:
  - `Accept: application/json` (or `text/markdown` on web routes)
  - `User-Agent`: Any descriptive client/agent identifier

### API Endpoints Summary

| Method | Path | Operation ID | Description |
|---|---|---|---|
| GET | `/services` | `listServices` | List all primary hardscaping and landscape services |
| GET | `/services/{slug}` | `getServiceBySlug` | Get full details and section breakdown for a service |
| GET | `/projects` | `listProjects` | List completed residential project portfolio |
| GET | `/projects/{slug}` | `getProjectBySlug` | Get case study, solutions, and imagery for a project |
| GET | `/locations` | `listLocations` | List all service area municipalities (optional `?county=`) |
| GET | `/locations/{slug}` | `getLocationBySlug` | Get town-specific service information and landscape details |
| GET | `/contact` | `getContactInfo` | Get company contact, licensing, hours, and inquiry links |

---

## 4. Rate Limiting Standards

All REST API endpoints enforce rate limiting to protect service availability while giving agents real-time self-throttling telemetry:

- **Limit**: 120 requests per 60-second window per client IP.
- **Response Headers**:
  - `RateLimit-Limit`: `120`
  - `RateLimit-Remaining`: Current remaining quota in window
  - `RateLimit-Reset`: Seconds remaining until window resets
  - `RateLimit-Policy`: `120;w=60`
  - `X-RateLimit-Limit`: `120`
  - `X-RateLimit-Remaining`: Current remaining quota
  - `X-RateLimit-Reset`: Seconds remaining
- **Exceeded Behavior (HTTP 429)**:
  - HTTP Status: `429 Too Many Requests`
  - `Retry-After`: Number of seconds to wait (e.g. `60`)
  - Response Body: RFC 9457 structured JSON error with resolution instructions.

---

## 5. Structured Error Model (RFC 9457)

All error responses from the API return standard RFC 9457 `application/problem+json` envelopes:

```json
{
  "type": "https://www.francionedesigngroup.com/docs#errors",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "projects not found",
  "code": "NOT_FOUND",
  "message": "projects not found",
  "resolution": "Check the slug against GET /api/v1/projects or review the OpenAPI spec at /openapi.json.",
  "path": "/api/v1/projects/unknown-slug",
  "error": {
    "code": "NOT_FOUND",
    "message": "projects not found",
    "resolution": "Check the slug against GET /api/v1/projects or review the OpenAPI spec at /openapi.json.",
    "path": "/api/v1/projects/unknown-slug"
  }
}
```

### Supported Error Codes
- `BAD_REQUEST` (400): Invalid query or path parameter.
- `UNAUTHORIZED` (401): Missing or invalid credentials.
- `NOT_FOUND` (404): Resource or slug does not exist.
- `METHOD_NOT_ALLOWED` (405): Method not supported (only GET allowed).
- `RATE_LIMIT_EXCEEDED` (429): Quota exhausted; consult `Retry-After`.
- `INTERNAL_ERROR` (500): Server error; retry after brief delay.

---

## 6. Versioning & Deprecation Policy

- **Current Version**: `1.0.0` (URI path `/api/v1`)
- **Stability Guarantee**: The `/api/v1` surface is immutable and backwards-compatible. Any breaking schema changes will be introduced under a new version prefix (e.g. `/api/v2`).
- **Deprecation Notice**: A minimum 6-month advance notice will precede the retirement of any version or endpoint.
- **Signaling**: Deprecated endpoints will return RFC 8594 `Deprecation: @<timestamp>` and `Sunset: <HTTP-date>` headers, with a `Link: <url>; rel="deprecation"` header.

---

## 7. Function Calling / LLM Tool Definitions

Agents can register the following function definitions for autonomous tool calling:

```json
[
  {
    "name": "fdg_list_services",
    "description": "List hardscaping, outdoor living, and landscape design services offered by Francione Design Group.",
    "parameters": {
      "type": "object",
      "properties": {}
    }
  },
  {
    "name": "fdg_get_service_detail",
    "description": "Get detailed information for a specific Francione Design Group service by slug.",
    "parameters": {
      "type": "object",
      "required": ["slug"],
      "properties": {
        "slug": {
          "type": "string",
          "enum": ["hardscaping-outdoor-living", "landscape-design"],
          "description": "Service slug"
        }
      }
    }
  },
  {
    "name": "fdg_list_locations",
    "description": "List municipalities in Monmouth and Ocean County served by Francione Design Group.",
    "parameters": {
      "type": "object",
      "properties": {
        "county": {
          "type": "string",
          "enum": ["Monmouth County", "Ocean County"],
          "description": "Optional county filter"
        }
      }
    }
  },
  {
    "name": "fdg_get_contact",
    "description": "Get official Francione Design Group phone, email, license number, and inquiry URLs.",
    "parameters": {
      "type": "object",
      "properties": {}
    }
  }
]
```

---

## 8. Discoverable Developer Resources

- **API Documentation**: https://www.francionedesigngroup.com/docs
- **OpenAPI JSON Spec**: https://www.francionedesigngroup.com/openapi.json
- **OpenAPI YAML Spec**: https://www.francionedesigngroup.com/api/openapi.yaml
- **Short Agent Guide (llms.txt)**: https://www.francionedesigngroup.com/llms.txt
- **Full Agent Manual (llms-full.txt)**: https://www.francionedesigngroup.com/llms-full.txt
- **XML Sitemap**: https://www.francionedesigngroup.com/sitemap.xml